dsh-multi-folder 0.1.3 → 0.1.4

package/README.md

@@ -56,6 +56,17 @@ Equivalent slash command for the user:
 
 The agent needs nothing extra: `read` / `glob` / `grep` work everywhere, and `write` / `edit` / `pwsh` / `bash` are intercepted and re-rooted automatically when the target path (or `workdir`) falls inside a configured secondary directory.
 
+## Permission model
+
+Each confined command runs under **exactly ONE writable root** — the workspace root the call is re-rooted to (the Windows ACL runner grants a single workspace write SID per process tree). Consequences:
+
+- A command whose cwd stays the **primary workspace cannot create files inside a secondary directory**. `git -C <secondary> commit`, `cd <secondary>` inside a script, `git clone <url> <secondary>`, or absolute-path writes all fail with an OS-level `Permission denied` (e.g. `fatal: Unable to create '.../.git/index.lock': Permission denied`).
+- Symmetrically, a command re-rooted to a secondary directory cannot write to the **primary workspace** (or another secondary directory) in the same invocation.
+- **Rule for file-creating commands: set `workdir` to the directory the command writes into.** For git, run the command from inside the repository (pass `workdir` pointing at it) instead of using `git -C` from the primary workspace.
+- Reads are unrestricted and need no `workdir`.
+
+When a shell run ends in such a denial and references a configured secondary directory, the plugin attaches a short diagnostic hint to the tool result explaining the workdir fix.
+
 ## How it works
 
 - **Interception** — a listener on the `tools/execute` around-dispatch waterfall short-circuits `write` / `edit` / `pwsh` / `bash` calls whose resolved path (or `workdir`) lands inside a configured secondary directory, and executes them with the session's standing sandbox policy **re-rooted to that directory** (`{ ...standingPolicy, workspaceRoot: secondaryDir }`). The mode itself is untouched, which is what gives every sandbox mode its identical primary-workspace semantics for free. Paths are canonicalized through `fs.resolve` + `processPath` before matching, so `..`, symlinks, and case differences behave correctly.

package/README.zh.md

@@ -56,6 +56,17 @@ dsh plugin --profile web add dsh-multi-folder
 
 Agent 无需任何额外操作：`read` / `glob` / `grep` 随处可用；`write` / `edit` / `pwsh` / `bash` 在路径（或 `workdir`）落入副目录时自动拦截并以该目录为沙箱根执行。
 
+## 权限模型
+
+每条受沙箱约束的命令只拥有**唯一一个可写根**——即本次调用被换根到的那个目录（Windows ACL runner 为每个进程树只授予一个工作区写 SID）。由此：
+
+- cwd 停留在**主工作区**的命令**不能在副目录创建文件**。`git -C <副目录> commit`、脚本内 `cd <副目录>`、`git clone <url> <副目录>`、按绝对路径写文件等都会以操作系统级 `Permission denied` 失败（例如 `fatal: Unable to create '.../.git/index.lock': Permission denied`）。
+- 对称地，被换根到副目录的命令在同一次调用中也**不能写主工作区**（或另一个副目录）。
+- **创建文件的命令必须把 `workdir` 设为它要写入的目录。** 对 git 而言，请进入仓库目录执行（`workdir` 指向该仓库），而不是从主工作区用 `git -C`。
+- 读操作不受限制，无需 `workdir`。
+
+当 shell 命令以这类拒绝失败且命令引用了已配置的副目录时，插件会在工具结果后附带一条简短的诊断提示，说明 workdir 的修正方式。
+
 ## 工作原理
 
 - **拦截**——监听 `tools/execute` 环绕分派瀑布，对解析路径（或 `workdir`）落在副目录内的 `write` / `edit` / `pwsh` / `bash` 调用短路，并以**换根后的会话站立策略**（`{ ...standingPolicy, workspaceRoot: secondaryDir }`）执行。模式本身不变，因此各种沙箱模式与主工作区的语义天然一致。匹配前先经 `fs.resolve` + `processPath` 规范化，`..`、符号链接与大小写差异均正确处理。

package/docs/design.md

@@ -206,6 +206,23 @@ window.__ModuleLoader__.load({
 
 ## Known limitations
 
+- Each confined command runs under exactly ONE writable root: the Windows ACL
+  runner grants a single workspace write SID per process tree (`--write-sid`
+  must match `--workspace`), and re-rooting replaces the root. A command whose
+  cwd stays the primary workspace therefore cannot create files inside a
+  secondary directory — `git -C <secondary> commit`, `cd <secondary>` inside a
+  script, `git clone <url> <secondary>`, and absolute-path writes fail with an
+  OS-level `Permission denied` (`fatal: Unable to create '.../.git/index.lock':
+  Permission denied`) that carries no sandbox marker. Symmetrically, a command
+  re-rooted to a secondary directory cannot write the primary workspace in the
+  same invocation. The injected prompt states the workdir rule, and a
+  `tools/post-execute` heuristic attaches a workdir-fix hint when a failed
+  `pwsh`/`bash` run both mentions a configured secondary directory and ends in
+  a denial (`permission denied` / `access … denied` / `is denied` / `eacces`;
+  the plugin's own `[sandbox: …]` marker lines are excluded from the scan).
+  Lifting this to real multi-root confinement needs an upstream change
+  (`SandboxExecutionPolicy` carrying extra write roots and the ACL runner
+  accepting several workspace write SIDs).
 - Intercepted secondary-directory writes bypass the fs observation policy: they emit
   no `fs/observed` event and do not participate in the `fs/write-intent` intent guard.
   This is deliberate — secondary directories sit outside the primary workspace's

package/lib/index.js

@@ -39,6 +39,12 @@
  *    directly. The `/multi-folder` command and the remote methods share
  *    one core so validation, canonicalization, and the config guard are
  *    identical on both channels.
+ * 7. Failure diagnosis: a `pwsh`/`bash` run that ends in an OS-level
+ *    `Permission denied` touching a secondary working directory (the ACL
+ *    runner confines each process tree to ONE writable root, so `git -C
+ *    <secondary>` launched from the primary workspace cannot write the
+ *    repo) gets a workdir-fix hint attached as an additional context at
+ *    the `tools/post-execute` boundary.
  */
 
 import { join } from 'node:path'
@@ -321,6 +327,100 @@ export function apply(ctx) {
     return text
   }
 
+  // -------------------------------------------- failure diagnosis (post-exec)
+  // The Windows ACL runner confines each process tree to exactly ONE writable
+  // workspace root (a single `--write-sid` that must match `--workspace`). A
+  // command that creates files inside a secondary directory while its cwd is
+  // confined elsewhere therefore fails with an OS-level `Permission denied`
+  // (git: `fatal: Unable to create '.../.git/index.lock': Permission denied`)
+  // and carries NO sandbox marker — the sandbox worked as designed. These
+  // helpers surface the workdir fix at the next tool-call boundary instead.
+
+  const DENIAL_MARK = /permission denied|access(?: is)? denied|eacces|is denied/i
+
+  const flattenResultText = (result) => {
+    const parts = []
+    if (result && Array.isArray(result.content)) {
+      for (const block of result.content) {
+        if (block && block.type === 'text' && typeof block.text === 'string') parts.push(block.text)
+      }
+    }
+    const value = result && result.value
+    if (value && typeof value === 'object') {
+      for (const stream of [value.stdout, value.stderr]) {
+        if (stream && typeof stream.text === 'string') parts.push(stream.text)
+      }
+    }
+    // The plugin's own `[sandbox: ...]` markers describe runner-level denials,
+    // not path-level EACCES; keep them out of the scan.
+    return parts
+      .join('\n')
+      .split('\n')
+      .filter((line) => !line.startsWith('[sandbox:'))
+      .join('\n')
+  }
+
+  /** The configured secondary dir a call's workdir lands in, or null. */
+  const workdirHitFor = async (exec) => {
+    if (!exec || !exec.agent || !exec.agent.session || !exec.agent.session.header) return null
+    const primary = exec.agent.session.header.cwd
+    if (typeof primary !== 'string' || primary.length === 0) return null
+    const dirs = dirsForSync(primary)
+    if (dirs === null) return null
+    const args = exec.arguments || {}
+    const rawWorkdir = typeof args.workdir === 'string' ? args.workdir : null
+    const joined =
+      rawWorkdir === null
+        ? String(primary)
+        : isAbsolute(rawWorkdir)
+          ? rawWorkdir
+          : String(primary).replace(/[\\/]+$/, '') + '/' + rawWorkdir
+    const target = await fs.resolve(joined, { cwd: primary })
+    const abs = fs.processPath(target)
+    return longestRootFirst(dirs).find((d) => pathInside(abs, d)) ?? null
+  }
+
+  /**
+   * A user-visible diagnostic for a shell run that ended in an OS-level
+   * permission denial touching a secondary working directory. Returns the
+   * hint text or undefined. Never throws — a hint failure must never touch
+   * the tool pipeline.
+   */
+  const permissionHint = async (exec, result) => {
+    try {
+      if (!exec || (exec.name !== 'pwsh' && exec.name !== 'bash')) return undefined
+      if (!exec.agent || !exec.agent.session || !exec.agent.session.header) return undefined
+      const exitCode =
+        result && result.value && typeof result.value.exitCode === 'number' ? result.value.exitCode : null
+      if (exitCode !== null && exitCode === 0) return undefined
+      if (!DENIAL_MARK.test(flattenResultText(result))) return undefined
+      const primary = exec.agent.session.header.cwd
+      if (typeof primary !== 'string' || primary.length === 0) return undefined
+      const dirs = dirsForSync(primary)
+      if (dirs === null) return undefined
+      const reRooted = await workdirHitFor(exec)
+      if (reRooted !== null) {
+        return (
+          'This command ran confined to the secondary working directory "' +
+          reRooted +
+          '", so writes OUTSIDE that directory (for example to the primary workspace or another secondary directory) were denied at the OS level. ' +
+          "Split the work into per-directory commands and set each command's `workdir` to the directory it writes into."
+        )
+      }
+      const cmdNorm = wsKey(String((exec.arguments || {}).command || ''))
+      const referenced = longestRootFirst(dirs).find((d) => cmdNorm.includes(wsKey(d)))
+      if (referenced === undefined) return undefined
+      return (
+        'This command ran with its cwd confined to the primary workspace, so creating files inside the secondary working directory "' +
+        referenced +
+        '" was denied at the OS level — each command can write inside only ONE root. ' +
+        'Re-run it with `workdir` set to that directory; for git, run the command from inside the repository instead of using `git -C` from the primary workspace.'
+      )
+    } catch {
+      return undefined
+    }
+  }
+
   // ------------------------------------------------------ prompt injection
   systemPrompt.section({
     name: SECTION_NAME,
@@ -336,8 +436,11 @@ export function apply(ctx) {
       return (
         'Secondary working directories are available in this session (dsh-multi-folder plugin):\n' +
         dirs.map((d) => '- ' + d).join('\n') +
-        '\nYou have the SAME read/write/edit and command-execution permissions on these directories as on the primary workspace under the current sandbox mode. ' +
+        '\nYou have the SAME read/write/edit and command-execution permissions on these directories as on the primary workspace under the current sandbox mode, ' +
+        'but each command can write inside only ONE root — the directory its workdir resolves to. ' +
+        'A command whose cwd stays the primary workspace CANNOT create files inside a secondary directory. ' +
         'For shell tools, pass `workdir` pointing inside one of these directories — foreground and background (`run_in_background`) runs alike. ' +
+        'File-creating commands, git included, MUST set `workdir` to the secondary directory: do not run `git -C <secondary>` or `cd <secondary>` inside a command launched from the primary workspace. ' +
         'Reads from these directories work without `workdir`. The primary workspace remains the default working directory.'
       )
     },
@@ -358,17 +461,21 @@ export function apply(ctx) {
   // --------------------------------------- notification (tool-call boundary)
   ctx.on('tools/post-execute', async (exec, result, next) => {
     const decision = await next()
-    const text = takeNotice(exec.agent)
-    if (text === undefined) return decision
-    const msg = noticeMessage(text)
+    const extras = []
+    const notice = takeNotice(exec.agent)
+    if (notice !== undefined) extras.push(notice)
+    const hint = await permissionHint(exec, result)
+    if (hint !== undefined) extras.push(hint)
+    if (extras.length === 0) return decision
+    const msgs = extras.map((text) => noticeMessage(text))
     if (decision.kind === 'block') {
       return {
         kind: 'block',
         feedback: decision.feedback,
-        additionalContexts: [msg, ...(decision.additionalContexts || [])],
+        additionalContexts: [...msgs, ...(decision.additionalContexts || [])],
       }
     }
-    return { ...decision, additionalContexts: [msg, ...(decision.additionalContexts || [])] }
+    return { ...decision, additionalContexts: [...msgs, ...(decision.additionalContexts || [])] }
   })
 
   // ------------------------------------------------- tool-pipeline intercept

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-multi-folder",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "DeepSeek Harness plugin: secondary working directories for a project. The agent keeps the primary workspace as cwd, gains equal write/exec permissions on configured secondary directories under workspace-write mode, and is notified of configuration changes at the next message boundary. Configurable from the session header AND from the session-creation page (before the first message) through a sessionless multiFolder remote API.",
   "keywords": [
     "dsh-plugin",