@idlercloud/dsh-git-bash 0.2.0 → 0.3.0

package/README.en.md

@@ -36,9 +36,11 @@ In addition, the existing pwsh tool is still kept, because cases such as the reg
 
 Currently verified only with DSH `0.2.2-rc.1`. Both the compatibility declaration and DSH peer dependencies are restricted to that version. Revalidate the plugin before upgrading DSH.
 
-**It does not go through a file sandbox, so it runs only under full access.**
+**It does not go through a file sandbox, so it runs only under `danger-full-access`.**
 
-Git Bash is an MSYS2 process. Under the Windows restricted token it needs fork, pipes and a private temp directory, and behaves unreliably, so this plugin has no usable sandbox backend. The plugin checks the file policy before invoking the tool and refuses non-full-access calls outright.
+Git Bash is an MSYS2 process. Under the Windows restricted token it needs fork, pipes and a private temp directory, and behaves unreliably, so this plugin has no usable sandbox backend. The plugin checks the file policy of each call before spawning and refuses anything other than `danger-full-access`.
+
+In a narrower session, the model can retry the same command with `sandbox_permissions: "danger-full-access"` and a `justification`; the host asks the user for approval, and the grant applies to that one call only. When the host composes no approval service, that path is unavailable, so use `pwsh` or switch the session policy.
 
 ## Non-goals
 
@@ -56,7 +58,7 @@ Git Bash is an MSYS2 process. Under the Windows restricted token it needs fork,
 - Git for Windows installed (provides `bash.exe`).
 - DSH `0.2.2-rc.1`.
 
-Desktop is a special case: normally install through the built-in plugin manager by entering the package name `@idlercloud/dsh-git-bash`. To install a specific version, enter `@idlercloud/dsh-git-bash@0.2.0`.
+Desktop is a special case: normally install through the built-in plugin manager by entering the package name `@idlercloud/dsh-git-bash`. To install a specific version, enter `@idlercloud/dsh-git-bash@0.3.0`.
 
 Otherwise, install into the target profile:
 
@@ -121,7 +123,7 @@ npm test
 npm run test:git-bash
 ```
 
-`npm test` builds and runs unit tests plus a real tool-service integration test. The integration test asserts permission enforcement through the real `ToolsService` and execution pipeline, without Git Bash or a running DSH instance. It explicitly skips non-Windows platforms because the plugin only registers its guard on Windows.
+`npm test` builds and runs unit tests plus a real tool-service integration test. The integration test asserts permission enforcement and the one-time escalation flow through the real `ToolsService` and execution pipeline, without Git Bash or a running DSH instance. It explicitly skips non-Windows platforms because the check runs only on Windows.
 
 `npm run test:git-bash` separately builds and runs `test/harness.mjs`, requiring Windows and an available Git Bash installation. It executes commands through real cordis and dsh-bash-local and asserts the results, returning a nonzero exit code on failure. It is excluded from the default test suite and does not require starting DSH.
 

package/README.md

@@ -36,9 +36,11 @@
 
 目前仅在 DSH `0.2.2-rc.1` 上验证，兼容性声明与 DSH peer 依赖均限定为该版本。升级 DSH 前需要重新验证本插件。
 
-**不经过文件沙箱，因此只在完全权限下运行**。
+**不经过文件沙箱，只在 `danger-full-access` 下运行。**
 
-Git Bash 是 MSYS2 进程，在 Windows 受限令牌下需要 fork、管道与私有临时目录，行为不可靠，所以本插件没有可用的沙箱后端。插件会在调用工具前检查文件策略，非完全权限会直接拒绝调用。
+Git Bash 是 MSYS2 进程，在 Windows 受限令牌下需要 fork、管道与私有临时目录，行为不可靠，所以本插件没有可用的沙箱后端。插件在 spawn 之前检查这次调用的文件策略，不是 `danger-full-access` 就拒绝。
+
+受限会话里，模型可以带 `sandbox_permissions: "danger-full-access"` 和 `justification` 重试同一条命令，由宿主弹出审批；批准只对这一次调用生效，会话策略不变。宿主没有装配审批服务时，这条路径不可用，只能切换会话策略或改用 `pwsh`。
 
 ## 非目标
 
@@ -56,7 +58,7 @@ Git Bash 是 MSYS2 进程，在 Windows 受限令牌下需要 fork、管道与
 - 已安装 Git for Windows（含 `bash.exe`）。
 - DSH `0.2.2-rc.1`。
 
-桌面端是特殊的，一般通过内置的插件管理器安装，输入包名 `@idlercloud/dsh-git-bash` 即可安装，如需安装特定版本，可以输入 `@idlercloud/dsh-git-bash@0.2.0`。
+桌面端是特殊的，一般通过内置的插件管理器安装，输入包名 `@idlercloud/dsh-git-bash` 即可安装，如需安装特定版本，可以输入 `@idlercloud/dsh-git-bash@0.3.0`。
 
 其他情况下，把插件安装到目标 profile：
 
@@ -121,7 +123,7 @@ npm test
 npm run test:git-bash
 ```
 
-`npm test` 会先构建，再运行单元测试和真实工具服务集成测试。集成测试通过真实 `ToolsService` 与工具执行流水线断言权限拦截，无需安装 Git Bash 或启动 DSH；由于插件只在 Windows 注册守卫，该用例在非 Windows 平台明确跳过。
+`npm test` 会先构建，再运行单元测试和真实工具服务集成测试。集成测试通过真实 `ToolsService` 与工具执行流水线断言权限拦截与单次提权流程，无需安装 Git Bash 或启动 DSH；由于插件只在 Windows 执行该检查，该用例在非 Windows 平台明确跳过。
 
 `npm run test:git-bash` 单独构建并运行 `test/harness.mjs`，需要 Windows 和可用的 Git Bash。它使用真实 cordis 与 dsh-bash-local 执行命令并断言检查结果，失败时返回非零退出码，不属于默认测试集，也不需要启动 DSH。
 

package/lib/index.d.ts

@@ -7,7 +7,7 @@
  * 本插件只做三件事：
  * - 解析 Git for Windows 里 bash.exe 的绝对路径并调用
  * - 给模型补一段系统提示词，说明这个是 MSYS 的 bash；
- * - 在会话文件策略不是完全权限时，于 spawn 之前拒绝 `bash` 调用。
+ * - 文件策略不是完全权限时，于 spawn 之前拒绝 `bash` 调用；受限会话可申请单次提权。
  *
  * @module dsh-git-bash
  */
@@ -29,7 +29,7 @@ export type PluginConfig = BashConfig & {
     bashPath?: string;
 };
 /**
- * 挂载执行器与权限闸门。
+ * 挂载执行器与系统提示词。
  *
  * @param ctx - 挂载点 context（位于 isolate 隔离作用域内）。
  * @param config - 组合条目配置，可含 bashPath / cwd / timeoutMs 等。

package/lib/index.js

@@ -7,19 +7,19 @@
  * 本插件只做三件事：
  * - 解析 Git for Windows 里 bash.exe 的绝对路径并调用
  * - 给模型补一段系统提示词，说明这个是 MSYS 的 bash；
- * - 在会话文件策略不是完全权限时，于 spawn 之前拒绝 `bash` 调用。
+ * - 文件策略不是完全权限时，于 spawn 之前拒绝 `bash` 调用；受限会话可申请单次提权。
  *
  * @module dsh-git-bash
  */
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local';
 import z from '@deepseek-ai/schemastery';
-import { bashDenialReason, FULL_ACCESS_MODE, installBashGuard } from './guard.js';
+import { bashDenialReason, FULL_ACCESS_MODE } from './policy.js';
 import { installGitBashPrompt } from './prompt.js';
 import { BashResolver } from './resolve.js';
 import { normalizeWorkdir } from './workdir.js';
 /** 加载器读取的插件元数据。 */
 export const name = '@idlercloud/dsh-git-bash';
-export const inject = ['subprocess', 'tools'];
+export const inject = ['subprocess'];
 export const Config = z.object({
     ...LocalBashExecutor.Config.dict,
     bashPath: z.string().description('Git Bash 路径，可使用绝对路径、相对路径或 PATH 中的可执行文件名。'),
@@ -38,7 +38,11 @@ class GitBashExecutor extends LocalBashExecutor {
         return FULL_ACCESS_MODE;
     }
     assertPolicy(spec) {
-        const reason = bashDenialReason({ mode: spec.sandboxPolicy?.mode });
+        // 工具会把审批通过的调用级 policy 写进 spec，所以这里看到的是升级后的模式。
+        const reason = bashDenialReason({
+            mode: spec.sandboxPolicy?.mode,
+            escalationAvailable: this.ctx.get('approval') !== undefined,
+        });
         if (reason) {
             const error = new Error(reason);
             error.code = 'GIT_BASH_POLICY_DENIED';
@@ -87,7 +91,7 @@ class GitBashExecutor extends LocalBashExecutor {
     }
 }
 /**
- * 挂载执行器与权限闸门。
+ * 挂载执行器与系统提示词。
  *
  * @param ctx - 挂载点 context（位于 isolate 隔离作用域内）。
  * @param config - 组合条目配置，可含 bashPath / cwd / timeoutMs 等。
@@ -98,8 +102,7 @@ export function apply(ctx, config) {
         return;
     const resolver = new BashResolver({ bashPath: config.bashPath });
     installGitBashPrompt(ctx);
-    installBashGuard(ctx);
-    ctx.logger.info('dsh-git-bash: `bash` is denied before spawn unless the session file policy is `%s`.', FULL_ACCESS_MODE);
+    ctx.logger.info('dsh-git-bash: `bash` requires `%s`; a narrower file policy can request per-call approval.', FULL_ACCESS_MODE);
     // 构造即注册：构造函数把执行器挂到隔离作用域的 ctx.shell 上，实例由 context 持有。
     new GitBashExecutor(ctx, config, resolver);
 }

package/lib/policy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * dsh-git-bash — 文件策略判定。
+ *
+ * 本插件的 `bash` 工具运行在 Git Bash（MSYS2）上，没有可用的沙箱后端：MSYS2 进程在
+ * Windows 受限令牌下需要 fork、创建管道、写入私有临时目录，无法可靠运行。因此执行器
+ * 只接受 `danger-full-access` 的调用。
+ *
+ * 受限会话里的调用在 spawn 之前拒绝。宿主装配了审批服务时，错误文本提示模型带
+ * `sandbox_permissions: "danger-full-access"` 和 `justification` 申请这一次调用的
+ * 提权；审批通过后工具把调用级 policy 换成 `danger-full-access`，执行器的检查随之放行。
+ *
+ * @module dsh-git-bash/policy
+ */
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
+/** 本执行器唯一接受的模式。 */
+export declare const FULL_ACCESS_MODE: SandboxMode;
+/** 收集到的调用事实。 */
+export interface BashAccessFacts {
+    mode?: SandboxMode;
+    hasPolicy?: boolean;
+    error?: unknown;
+    /** 宿主是否装配了审批服务。 */
+    escalationAvailable?: boolean;
+}
+/**
+ * 纯函数，不做 IO。只有精确的 `danger-full-access` 放行；有异常、缺服务、
+ * 模式未知都返回拒绝文案。
+ *
+ * @param facts - 调用事实。
+ * @param facts.mode - 解析出来的沙箱模式，未解析时省略。
+ * @param facts.hasPolicy - 宿主是否提供 sandboxPolicy 服务，默认 true。
+ * @param facts.error - 解析策略时的异常，没有时省略。
+ * @param facts.escalationAvailable - 宿主是否提供审批服务，默认 false。
+ * @returns 拒绝原因；undefined 表示放行。
+ */
+export declare function bashDenialReason({ mode, hasPolicy, error, escalationAvailable, }?: BashAccessFacts): string | undefined;

package/lib/policy.js

@@ -0,0 +1,45 @@
+/** 本执行器唯一接受的模式。 */
+export const FULL_ACCESS_MODE = 'danger-full-access';
+/** 拒绝文案的固定前缀：说明 Git Bash 与文件沙箱的关系。 */
+const WHY = '`bash` runs in Git for Windows Git Bash, which cannot enforce the DSH file sandbox, ' +
+    'so it runs only under `danger-full-access`. ';
+/** 有审批服务时给出的单次提权路径。 */
+const ESCALATION = 'Retry the same command with `sandbox_permissions: "danger-full-access"` and a `justification` ' +
+    'to request one-time approval for this call. ';
+/** 其余情况给出的退路。 */
+const NEXT = 'Use the `pwsh` tool for commands this policy governs, or ask the user to switch the session access mode.';
+/** 把任意抛出物转成一段可读的原因。 */
+function describeError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/**
+ * 把具体原因接在 {@link WHY} 之后，拼成一条拒绝文案。
+ * @param detail - 本次拒绝的具体原因。
+ * @param escalation - 是否附上单次提权路径。
+ */
+function denyReason(detail, escalation = false) {
+    return WHY + detail + (escalation ? ESCALATION : '') + NEXT;
+}
+/**
+ * 纯函数，不做 IO。只有精确的 `danger-full-access` 放行；有异常、缺服务、
+ * 模式未知都返回拒绝文案。
+ *
+ * @param facts - 调用事实。
+ * @param facts.mode - 解析出来的沙箱模式，未解析时省略。
+ * @param facts.hasPolicy - 宿主是否提供 sandboxPolicy 服务，默认 true。
+ * @param facts.error - 解析策略时的异常，没有时省略。
+ * @param facts.escalationAvailable - 宿主是否提供审批服务，默认 false。
+ * @returns 拒绝原因；undefined 表示放行。
+ */
+export function bashDenialReason({ mode, hasPolicy = true, error, escalationAvailable = false, } = {}) {
+    if (error !== undefined) {
+        return denyReason(`Resolving the file policy failed (${describeError(error)}). `);
+    }
+    if (hasPolicy === false) {
+        return denyReason('This host exposes no sandbox policy service, so the file policy cannot be verified. ');
+    }
+    if (mode === FULL_ACCESS_MODE)
+        return undefined;
+    const actual = mode === undefined ? 'unknown' : `\`${mode}\``;
+    return denyReason(`The file policy is ${actual}. `, escalationAvailable && mode !== undefined);
+}

package/lib/prompt.js

@@ -12,7 +12,8 @@ export const GIT_BASH_PROMPT = 'The `bash` tool runs commands in Git for Windows
     '`workdir` accepts Windows paths (`C:/...`) and MSYS drive paths (`/c/...`, normalized to `C:/...`); ' +
     'drive-less MSYS paths such as `/tmp` are rejected. `workdir` is not shell-expanded, so `~` and `$VAR` ' +
     'are taken literally. ' +
-    'This tool does not support a file sandbox, so it is available only under `danger-full-access`. ' +
+    'This tool has no file sandbox: under a narrower policy, widen this call directly to ' +
+    '`danger-full-access`; `workspace-write` does not make Git Bash runnable. ' +
     'Prefer `bash` for command-line work. Use `pwsh` only when the task is Windows-native, such as cmdlets, ' +
     'the registry, services, and WMI, or when `bash` is unavailable.';
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idlercloud/dsh-git-bash",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Git for Windows bash tool for DSH on Windows; fork of Fishquito7/dsh-gitbash.",
   "author": "idlercloud",
   "type": "module",

package/lib/guard.d.ts

@@ -1,47 +0,0 @@
-/**
- * dsh-git-bash — 非完全权限拒绝。
- *
- * 本插件的 `bash` 工具运行在 Git Bash（MSYS2）上。MSYS2 进程在 Windows 受限令牌下
- * 需要 fork、创建管道、写入私有临时目录，无法可靠运行，因此没有可用的沙箱后端。
- * 工具只在文件策略解析为 `danger-full-access` 时执行：有会话时读该会话的策略，
- * 无会话时读实例默认模式；`read-only`、`workspace-write`、策略缺失或解析失败时，
- * 调用在 spawn 之前返回拒绝。
- *
- * 拒绝点用 `ctx.tools.guard()`：guard 在每个 `tools/pre-execute` 监听器之后、
- * 工具体执行之前求值，只能拒绝、不能放行。把检查放在 pre-execute 监听器里会被
- * 其他策略或审批插件的 allow 覆盖，guard 不会。
- *
- * 插件入口只在 win32 调用本函数。
- *
- * @module dsh-git-bash/guard
- */
-import type { Context } from '@deepseek-ai/cordis';
-import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
-export declare const BASH_TOOL_NAME = "bash";
-export declare const FULL_ACCESS_MODE: SandboxMode;
-/** 收集到的调用事实。 */
-export interface BashAccessFacts {
-    mode?: SandboxMode;
-    hasPolicy?: boolean;
-    error?: unknown;
-}
-/**
- * 纯函数，不做 IO。只有精确的 `danger-full-access` 放行；有异常、缺服务、
- * 模式未知都返回拒绝文案。
- *
- * @param facts - 调用事实。
- * @param facts.mode - 解析出来的沙箱模式，未解析时省略。
- * @param facts.hasPolicy - 宿主是否提供 sandboxPolicy 服务，默认 true。
- * @param facts.error - 解析策略时的异常，没有时省略。
- * @returns 拒绝原因；undefined 表示放行。
- */
-export declare function bashDenialReason({ mode, hasPolicy, error }?: BashAccessFacts): string | undefined;
-/**
- * 注册工具层守卫。
- *
- * 只处理名为 `bash` 的调用，其余调用直接放行，不读取策略。
- *
- * @param ctx - 插件 context，需已注入 tools 服务。
- * @returns 撤销器。
- */
-export declare function installBashGuard(ctx: Context): () => void;

package/lib/guard.js

@@ -1,100 +0,0 @@
-import { scopeOf } from '@deepseek-ai/dsh-scope';
-export const BASH_TOOL_NAME = 'bash';
-export const FULL_ACCESS_MODE = 'danger-full-access';
-/** 拒绝文案的前后缀：原因之后给两条出路 */
-const WHY = '`bash` runs in Git for Windows Git Bash, which cannot enforce the DSH file sandbox, ' +
-    'so it runs only while the file policy is `danger-full-access`. ';
-const NEXT = ' Use the `pwsh` tool for commands this policy governs, or ask the user to switch the session access mode.';
-/** 把任意抛出物转成一段可读的原因。 */
-function describeError(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-/**
- * 把原因接在 {@link WHY} 之后，拼成一条拒绝文案。
- * @param detail - 本次拒绝的具体原因。
- */
-function denyReason(detail) {
-    return WHY + detail + NEXT;
-}
-/**
- * 纯函数，不做 IO。只有精确的 `danger-full-access` 放行；有异常、缺服务、
- * 模式未知都返回拒绝文案。
- *
- * @param facts - 调用事实。
- * @param facts.mode - 解析出来的沙箱模式，未解析时省略。
- * @param facts.hasPolicy - 宿主是否提供 sandboxPolicy 服务，默认 true。
- * @param facts.error - 解析策略时的异常，没有时省略。
- * @returns 拒绝原因；undefined 表示放行。
- */
-export function bashDenialReason({ mode, hasPolicy = true, error } = {}) {
-    if (error !== undefined) {
-        return denyReason(`Resolving the file policy failed (${describeError(error)}).`);
-    }
-    if (hasPolicy === false) {
-        return denyReason('This host exposes no sandbox policy service, so the file policy cannot be verified.');
-    }
-    if (mode !== FULL_ACCESS_MODE) {
-        const actual = mode === undefined ? 'an unknown mode' : `\`${mode}\``;
-        return denyReason(`The file policy is ${actual}.`);
-    }
-    return undefined;
-}
-/**
- * 收集一次调用的事实：sandboxPolicy 服务、解析出的模式。
- *
- * 所有异常都转成 facts，不向工具层抛出：抛出的异常会成为普通工具错误，模型无法
- * 区分这是权限拒绝。
- *
- * @param ctx - 插件 context。
- * @param agent - 发起调用的 agent。
- * @returns `{ hasPolicy, mode?, error? }`。
- */
-function collectFacts(ctx, agent) {
-    const service = ctx.get('sandboxPolicy');
-    if (service === undefined)
-        return { hasPolicy: false };
-    try {
-        const { mode } = service.resolve({ session: agent?.session });
-        return { hasPolicy: true, mode };
-    }
-    catch (error) {
-        return { hasPolicy: true, error };
-    }
-}
-/**
- * 这次 `bash` 调用是否属于本插件注册的工具。
- *
- * 工具层允许 agent 作用域的同名定义遮蔽全局工具。其他插件可能注册自己的 `bash`，
- * 策略与本插件不同；只按名字拦截会拒绝这些工具。因此比较调用方本步能执行的定义与
- * 插件注册作用域中的定义：两者都存在且是同一个对象时才由本插件裁决。
- *
- * @param ctx - 插件 context。
- * @param exec - 待执行的工具调用。
- * @returns 该调用是否由本插件裁决。
- */
-function ownsBashCall(ctx, exec) {
-    const visible = ctx.tools.executable(BASH_TOOL_NAME, exec.agent, exec.toolSet);
-    const registered = ctx.tools.get(BASH_TOOL_NAME, scopeOf(ctx));
-    return visible !== undefined && visible === registered;
-}
-/**
- * 注册工具层守卫。
- *
- * 只处理名为 `bash` 的调用，其余调用直接放行，不读取策略。
- *
- * @param ctx - 插件 context，需已注入 tools 服务。
- * @returns 撤销器。
- */
-export function installBashGuard(ctx) {
-    return ctx.tools.guard((exec) => {
-        if (exec.name !== BASH_TOOL_NAME)
-            return undefined;
-        if (!ownsBashCall(ctx, exec))
-            return undefined;
-        const reason = bashDenialReason(collectFacts(ctx, exec.agent));
-        if (reason === undefined)
-            return undefined;
-        ctx.logger.info('dsh-git-bash: denied `bash` before spawn — %s', reason);
-        return reason;
-    });
-}