@yiln-dsh/dsh-plugin-sandbox-guidance 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @yiln-dsh/dsh-plugin-sandbox-guidance
+
+A Host-only DSH plugin that explains one confusing sandbox failure to the model:
+when a bash call asks for a mode that is not strictly wider than the current
+sandbox mode.
+
+It does not change sandbox policy, bypass approval, rewrite tool arguments, or
+replace the built-in bash executor. The native failure remains an error and the
+command remains unexecuted.
+
+## Behavior
+
+The plugin adds a `systemPrompt` section that tells the model to omit
+`sandbox_permissions` during ordinary calls and to explain this failure instead
+of repeating it blindly. It also listens to `tools/post-execute` and replaces
+only the matching bash failure text with a diagnostic containing:
+
+- the fact that bash did not run;
+- the requested sandbox mode;
+- the current effective mode;
+- whether the retry should omit `sandbox_permissions` or request a genuinely wider mode.
+
+Other bash failures pass through unchanged.
+
+## Install
+
+The published package is `@yiln-dsh/dsh-plugin-sandbox-guidance@0.1.0`.
+
+```bash
+dsh plugin --profile web add @yiln-dsh/dsh-plugin-sandbox-guidance@latest
+```
+
+Restart `dsh web` after installing the package so the Host composition loads the
+new row.
+
+## Limitations
+
+`tools/pre-execute` and `tools/post-execute` receive immutable tool arguments.
+This plugin can explain a failure and guide the next model step, but it cannot
+silently convert an invalid escalation into a valid one. Removing the strict
+sandbox check still requires a DSH core patch or fork.
+
+## Layout
+
+| File | Content |
+| --- | --- |
+| `index.js` | Host system prompt section and bash failure diagnostic. |
+| `cordis.patch.yml` | Composition patch that mounts the Host row. |

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-plugin-sandbox-guidance bundle patch.
+#
+# Adds a Host-only prompt/result diagnostic; it never changes sandbox policy or
+# replaces the native bash executor.
+
+- insert:
+    - id: sandbox-guidance
+      name: '@yiln-dsh/dsh-plugin-sandbox-guidance'
+      inject:
+        - tools
+        - systemPrompt

package/index.js

@@ -0,0 +1,60 @@
+/**
+ * Explains non-widening sandbox errors to the model without changing execution.
+ * The native bash tool remains fail-closed; this package only improves recovery
+ * guidance when a caller repeats the current sandbox mode.
+ */
+
+export const name = "sandbox-guidance";
+export const inject = ["tools", "systemPrompt"];
+
+const NON_WIDENING_ERROR = /^sandbox escalation to "([^"]+)" is not strictly wider than this call's current "([^"]+)" mode$/u;
+
+/**
+ * Turn the native sandbox error into a model-facing diagnostic that says what
+ * ran, what did not run, and which retry shape is valid.
+ */
+export function explainSandboxFailure(message) {
+  if (typeof message !== "string") return undefined;
+  const match = NON_WIDENING_ERROR.exec(message);
+  if (match === null) return undefined;
+  const requested = match[1];
+  const effective = match[2];
+  const sameMode = requested === effective;
+  return [
+    "Bash was not executed; this failure happened before the command ran.",
+    `Cause: sandbox_permissions requested \"${requested}\", but the current effective sandbox mode is \"${effective}\".`,
+    sameMode
+      ? "The requested mode is already active, so sandbox_permissions must be omitted for the retry."
+      : "sandbox_permissions is only valid for a retry that requests a strictly wider mode; do not retry with this mode.",
+    "Explain this cause to the user instead of silently repeating the same bash call.",
+  ].join(" ");
+}
+
+const SYSTEM_PROMPT = [
+  "Sandbox escalation recovery:",
+  "- Do not include sandbox_permissions in an ordinary bash call.",
+  "- Only include it when retrying a call that was actually denied by the sandbox and the requested mode is strictly wider than the effective mode.",
+  "- If a bash result says the requested mode is not strictly wider than the current mode, state that the command did not run, explain the requested and effective modes, and retry without sandbox_permissions when the current mode is sufficient.",
+  "- If a wider mode is genuinely required, explain why to the user and request approval rather than repeating the failed call.",
+].join("\n");
+
+export function apply(ctx) {
+  const order = typeof ctx.systemPrompt.getSectionOrder === "function"
+    ? ctx.systemPrompt.getSectionOrder("TOOL_BASH") + 1
+    : 105;
+  ctx.systemPrompt.section({
+    name: "tool:sandbox-guidance",
+    order,
+    text: SYSTEM_PROMPT,
+  });
+
+  ctx.on("tools/post-execute", (exec, result, next) => {
+    if (exec.name !== "bash" || result.isError !== true) return next();
+    const explained = explainSandboxFailure(result.error?.message);
+    if (explained === undefined) return next();
+    return {
+      kind: "accept",
+      content: [{ type: "text", text: explained }],
+    };
+  });
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@yiln-dsh/dsh-plugin-sandbox-guidance",
+  "version": "0.1.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "DSH Host plugin that explains non-widening sandbox failures to the model and user without changing execution policy.",
+  "type": "module",
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "files": [
+    "index.js",
+    "cordis.patch.yml",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=4.0.2",
+    "@deepseek-ai/dsh-system-prompt": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "license": "MIT"
+}