@mars-sea/dsh-commandcode-provider 0.11.12 → 0.11.13

package/lib/index.d.ts

@@ -738,6 +738,16 @@ declare class CommandCodeAccountPool {
   private pick;
 }
 //#endregion
+//#region src/command-guard.d.ts
+/**
+ * The auto-approve strictness a user picks (`Config.commandGuardLevel`). Each
+ * level is the probability every verdict must reach before the guard grants
+ * `allowed-once`; a higher level approves less, on stronger evidence. Three
+ * presets replace a free-form probability because the useful range is narrow
+ * and a hand-typed 0.6 silently turns the guard into a rubber stamp.
+ */
+type CommandGuardLevel = 'high' | 'medium' | 'low';
+//#endregion
 //#region src/capabilities.d.ts
 /**
  * Static capability snapshot for the Command Code provider: model →
@@ -1915,23 +1925,18 @@ interface Config {
    * opt-in, and the command text (plus the agent's own description of it) is
    * sent to Command Code to judge. Only commands a policy already wanted a
    * human to look at are ever judged, and only a confident "safe" verdict
-   * (`commandGuardThreshold`) skips the prompt — every other outcome, including
+   * (`commandGuardLevel`) skips the prompt — every other outcome, including
    * any failure of the decision call itself, delegates to the normal approval
    * flow. See `./command-guard.ts`.
    */
   commandGuard?: boolean;
   /**
-   * Minimum probability of "safe" that lets the guard skip the approval prompt;
-   * defaults to 0.9. Lowering it approves more, on less evidence.
-   */
-  commandGuardThreshold?: number;
-  /**
-   * Milliseconds the guard waits for a decision before falling back to the
-   * human prompt; defaults to 1500. This is a latency budget for an interactive
-   * approval, not a request timeout — a decision that arrives late is useless,
-   * because the user is staring at a prompt.
+   * How confident every verdict must be before the guard skips the approval
+   * prompt: `high` (0.95), `medium` (0.9, the default) or `low` (0.8). A lower
+   * level approves more, on less evidence. The decision budget is fixed
+   * (`COMMAND_GUARD_TIMEOUT_MS`), so this is the guard's only tuning knob.
    */
-  commandGuardTimeoutMs?: number;
+  commandGuardLevel?: CommandGuardLevel;
   /**
    * Whether requests enforce zero data retention: the provider then routes
    * them only through upstreams that keep no prompts/completions and never

package/lib/index.js

@@ -6950,8 +6950,8 @@ function buildCommandCodeTuiSection(deps) {
 				kind: "boolean",
 				label: "AI command guard",
 				descriptions: { zh: "AI 命令安全预判" },
-				hint: "typesafe/jev judges whether a shell command is safe and auto-approves it; everything else asks as usual. Off by default.",
-				hintDescriptions: { zh: "由 typesafe/jev 判断 shell 命令是否安全，安全则自动放行，其余照常弹窗。默认关闭。" },
+				hint: "typesafe/jev judges whether a shell command is safe; sandbox escalations also need separate scope and necessity verdicts. All must be confident enough; everything else asks as usual. Off by default.",
+				hintDescriptions: { zh: "由 typesafe/jev 判断 shell 命令是否安全；沙箱提权还要分别判断范围与必要性，三项都足够确定才自动放行，其余照常弹窗。默认关闭。" },
 				format: (value) => value === true ? "true" : "false",
 				parse: (text) => ({
 					kind: "set",
@@ -6959,38 +6959,36 @@ function buildCommandCodeTuiSection(deps) {
 				})
 			},
 			{
-				path: ["commandGuardThreshold"],
+				path: ["commandGuardLevel"],
 				group: "advanced",
-				kind: "number",
-				label: "Auto-approve threshold (0.5-1)",
-				descriptions: { zh: "自动放行阈值（0.5-1）" },
-				hint: "Approve when typesafe/jev rates the command \"safe\" at least this likely; default 0.9.",
-				hintDescriptions: { zh: "typesafe/jev 判定\"安全\"的概率达到该值即放行，默认 0.9。" },
-				parse: (text) => {
-					const trimmed = text.trim();
-					if (trimmed === "") return { kind: "clear" };
-					const parsed = Number(trimmed);
-					return Number.isFinite(parsed) && parsed >= .5 && parsed <= 1 ? {
-						kind: "set",
-						value: parsed
-					} : void 0;
-				}
-			},
-			{
-				path: ["commandGuardTimeoutMs"],
-				group: "advanced",
-				kind: "number",
-				label: "Judgement timeout (ms, 200-10000)",
-				descriptions: { zh: "判定超时（毫秒，200-10000）" },
-				hint: "If typesafe/jev does not answer in time, the normal prompt appears; default 1500.",
-				hintDescriptions: { zh: "typesafe/jev 超过该时间未返回就照常弹窗，默认 1500。" },
+				kind: "select",
+				label: "Auto-approve threshold",
+				descriptions: { zh: "自动放行阈值" },
+				hint: "How confident typesafe/jev must be before a command runs without asking. Default: medium.",
+				hintDescriptions: { zh: "typesafe/jev 需要多确定才免弹窗放行；默认「中」。" },
+				options: [
+					{
+						value: "high",
+						label: "High (0.95, approves least)",
+						descriptions: { zh: "高（0.95，放行最少）" }
+					},
+					{
+						value: "medium",
+						label: "Medium (0.9)",
+						descriptions: { zh: "中（0.9）" }
+					},
+					{
+						value: "low",
+						label: "Low (0.8, approves most)",
+						descriptions: { zh: "低（0.8，放行最多）" }
+					}
+				],
+				format: (value) => value === "high" || value === "low" ? value : "medium",
 				parse: (text) => {
 					const trimmed = text.trim();
-					if (trimmed === "") return { kind: "clear" };
-					const parsed = Number(trimmed);
-					return Number.isFinite(parsed) && parsed >= 200 && parsed <= 1e4 ? {
+					return trimmed === "high" || trimmed === "medium" || trimmed === "low" ? {
 						kind: "set",
-						value: parsed
+						value: trimmed
 					} : void 0;
 				}
 			},
@@ -7311,8 +7309,6 @@ function transportBudgetMessage(failureMessage, maxRetries) {
 */
 /** Path of the decision endpoint, relative to `apiBase`. */
 const SYSTEMONE_ROUTE = "/provider/v1/systemone";
-/** Milliseconds a decision may take before the caller gives up on it. */
-const SYSTEMONE_DEFAULT_TIMEOUT_MS = 1500;
 /** The one error type this client throws. Callers fail closed on it. */
 var SystemOneError = class extends Error {
 	kind;
@@ -7570,13 +7566,40 @@ async function runSystemOne(deps, request, options = {}) {
 //#region src/command-guard.ts
 /** Tool names whose `arguments.command` this guard judges. */
 const COMMAND_GUARD_SHELL_TOOLS = ["bash", "pwsh"];
-/** Question id the safety verdict is keyed by. */
+/** Question id the primary safety verdict is keyed by. */
 const COMMAND_GUARD_QUESTION_ID = "safe";
-/** Decision budget; the approval prompt must not wait longer than this. */
-const COMMAND_GUARD_DEFAULT_TIMEOUT_MS = SYSTEMONE_DEFAULT_TIMEOUT_MS;
-/** Bounds of the configurable probability, mirrored by the settings schemas. */
-const COMMAND_GUARD_MIN_THRESHOLD = .5;
-const COMMAND_GUARD_MAX_TIMEOUT_MS = 1e4;
+/** Question id for the narrow-purpose part of a sandbox escalation. */
+const COMMAND_GUARD_ESCALATION_SCOPE_QUESTION_ID = "escalation_scope";
+/** Question id for the necessity/proportionality part of a sandbox escalation. */
+const COMMAND_GUARD_ESCALATION_NECESSITY_QUESTION_ID = "escalation_necessity";
+/** The selectable levels, strictest first (the order the settings surfaces list them in). */
+const COMMAND_GUARD_LEVELS = [
+	"high",
+	"medium",
+	"low"
+];
+/** Each level's probability threshold. */
+const COMMAND_GUARD_LEVEL_THRESHOLDS = {
+	high: .95,
+	medium: .9,
+	low: .8
+};
+/** The level an unset config reads as. */
+const COMMAND_GUARD_DEFAULT_LEVEL = "medium";
+/** Probability of "safe" at or above which the guard grants `allowed-once` by default. */
+const COMMAND_GUARD_DEFAULT_THRESHOLD = COMMAND_GUARD_LEVEL_THRESHOLDS[COMMAND_GUARD_DEFAULT_LEVEL];
+/** The threshold for a stored level; anything unrecognized reads as the default level. */
+function commandGuardThreshold(level) {
+	return typeof level === "string" && Object.hasOwn(COMMAND_GUARD_LEVEL_THRESHOLDS, level) ? COMMAND_GUARD_LEVEL_THRESHOLDS[level] : COMMAND_GUARD_DEFAULT_THRESHOLD;
+}
+/**
+* Decision budget; the approval prompt must not wait longer than this. Fixed
+* rather than configurable: it only bounds how long a late verdict can delay
+* the prompt, and every failure (a timeout included) already falls back to
+* asking the user, so there is nothing for a user to tune. 3 s leaves room for
+* credential resolution plus one decision round trip on a slow link.
+*/
+const COMMAND_GUARD_TIMEOUT_MS = 3e3;
 /**
 * Longest command the guard will send for judgement. A longer one is delegated
 * instead of truncated: a verdict on the first N characters of a command is a
@@ -7755,17 +7778,21 @@ function shellCommandOf(name, args) {
 /**
 * Build the decision request for one command.
 *
-* The question is deliberately one `noul`: a single probability is a decision
-* rule that can be explained, thresholded and logged in one line, and the
-* criteria carry the whole distinction between "reads, or writes reversibly
-* inside the project" and "everything else". The agent's own `description` is
-* included as context, but the criteria say the command text itself decides — a
+* A normal approval asks one question. A call that explicitly requests a wider
+* sandbox gets the same safety question plus two veto questions. This keeps the
+* common case cheap while making the broader permission change an explicit
+* decision: JEV must agree that the extra access has a narrow purpose and is
+* necessary, not merely that the command text looks familiar.
+*
+* The agent's own `description` and the harness's `reason` are included as
+* context, but the criteria say the command text itself decides — a
 * model-written description is a claim, not evidence.
 *
 * @param fact - the command and its context.
 * @returns the request to send.
 */
 function buildSafetyRequest(fact) {
+	const escalated = fact.sandboxPermissions !== void 0;
 	const lines = [
 		`Tool: ${fact.tool}`,
 		"Command:",
@@ -7777,24 +7804,43 @@ function buildSafetyRequest(fact) {
 	];
 	const question = {
 		type: "noul",
-		instructions: "Is it safe to run this command right now WITHOUT asking the user first? Judge the command text itself; a description is only a claim about it.",
+		instructions: escalated ? "Is it safe to run this command right now WITHOUT asking the user first, including the requested sandbox escalation? Judge the command text itself; a description or stated reason is only a claim about it." : "Is it safe to run this command right now WITHOUT asking the user first? Judge the command text itself; a description is only a claim about it.",
 		criteria: {
-			true: "Read-only, or its effects stay inside the current project and are trivially reversible: no data leaves the machine, nothing outside the project is modified, and no credentials, git history or remote state are touched.",
-			false: "Anything else. Deleting or overwriting files outside the project, rewriting or publishing git history, uploading data anywhere, installing system or global packages, changing permissions, ownership or credentials, killing processes, running as another user or as root, piping a download into a shell, or a command obfuscated enough that its effect cannot be read."
+			true: escalated ? "A normal, non-obfuscated read, build, or test operation whose outside-workspace effects are limited to conventional build/dependency caches or temporary files and are easily reversible: no unrelated user or system data is accessed, no data leaves the machine, and no credentials, git history or remote state are touched." : "Read-only, or its effects stay inside the current project and are trivially reversible: no data leaves the machine, nothing outside the project is modified, and no credentials, git history or remote state are touched.",
+			false: "Anything else. Broad or unrelated outside-workspace access, deleting or overwriting files outside the project, rewriting or publishing git history, uploading data anywhere, installing system or global packages, changing permissions, ownership or credentials, killing processes, running as another user or as root, piping a download into a shell, or a command obfuscated enough that its effect cannot be read."
 		}
 	};
+	const questions = { [COMMAND_GUARD_QUESTION_ID]: question };
+	if (escalated) {
+		questions[COMMAND_GUARD_ESCALATION_SCOPE_QUESTION_ID] = {
+			type: "noul",
+			instructions: "Is the requested wider sandbox access limited to a narrow, conventional purpose supported by this command, such as a build cache, dependency cache, or temporary directory, rather than unrelated user files, credentials, other projects, or the network?",
+			criteria: {
+				true: "The wider access is plausibly limited to conventional local build/dependency caches or temporary files required by the command, with no unrelated host data or remote transfer in scope.",
+				false: "The command needs broad or unrelated host access, cannot establish a narrow purpose, or would use the wider permission to reach credentials, other projects, user files, or the network."
+			}
+		};
+		questions[COMMAND_GUARD_ESCALATION_NECESSITY_QUESTION_ID] = {
+			type: "noul",
+			instructions: "Is the requested sandbox escalation necessary and proportionate for this one command, rather than broader than the command needs? Treat the stated reason as a claim to check against the command, not as proof.",
+			criteria: {
+				true: "The command and its stated purpose support a one-shot escalation that is needed for the task and is no broader than the requested effect requires.",
+				false: "The wider mode is unnecessary, broader than needed, unsupported by the command, or the command is too ambiguous to justify the extra authority."
+			}
+		};
+	}
 	return {
 		state: lines.join("\n"),
-		questions: { [COMMAND_GUARD_QUESTION_ID]: question }
+		questions
 	};
 }
 /**
-* Read the safety probability out of a decision response.
+* Read a probability out of a decision response.
 *
 * @param response - the parsed response.
 * @param questionId - the question id to read (defaults to the guard's own).
-* @returns the probability of "safe", or undefined when the answer is missing
-*   or is not a `noul` verdict.
+* @returns the probability, or undefined when the answer is missing or is not
+*   a `noul` verdict.
 */
 function safeProbabilityOf(response, questionId = COMMAND_GUARD_QUESTION_ID) {
 	const answer = response.answers[questionId];
@@ -7901,7 +7947,7 @@ var CommandGuard = class {
 		const agentDecisions = request.agent === void 0 ? void 0 : this.decisions.get(request.agent);
 		const memo = agentDecisions?.get(memoKey);
 		if (memo !== void 0) {
-			if (now - memo.at < 6e5) return this.verdict(memo.probability, settings.threshold, "memo", excerpt);
+			if (now - memo.at < 6e5) return this.verdict(memo, settings.threshold, "memo", excerpt, full.sandboxPermissions !== void 0);
 			agentDecisions?.delete(memoKey);
 		}
 		let response;
@@ -7923,12 +7969,28 @@ var CommandGuard = class {
 			reason: "the decision carried no safe verdict",
 			command: excerpt
 		};
+		let escalation;
+		if (full.sandboxPermissions !== void 0) {
+			const scope = safeProbabilityOf(response, COMMAND_GUARD_ESCALATION_SCOPE_QUESTION_ID);
+			const necessity = safeProbabilityOf(response, COMMAND_GUARD_ESCALATION_NECESSITY_QUESTION_ID);
+			if (scope === void 0 || necessity === void 0) return {
+				kind: "delegate",
+				reason: "the decision carried no complete sandbox-escalation verdict",
+				command: excerpt
+			};
+			escalation = {
+				scope,
+				necessity
+			};
+		}
+		const memoEntry = {
+			probability,
+			...escalation === void 0 ? {} : { escalation },
+			at: now
+		};
 		if (request.agent !== void 0) {
 			const decisions = agentDecisions ?? /* @__PURE__ */ new Map();
-			decisions.set(memoKey, {
-				probability,
-				at: now
-			});
+			decisions.set(memoKey, memoEntry);
 			while (decisions.size > 64) {
 				const oldest = decisions.keys().next();
 				if (oldest.done === true) break;
@@ -7936,19 +7998,44 @@ var CommandGuard = class {
 			}
 			this.decisions.set(request.agent, decisions);
 		}
-		return this.verdict(probability, settings.threshold, "model", excerpt);
+		return this.verdict(memoEntry, settings.threshold, "model", excerpt, full.sandboxPermissions !== void 0);
 	}
-	/** Apply the threshold to one probability. */
-	verdict(probability, threshold, source, command) {
-		return probability >= threshold ? {
+	/** Apply the threshold to the primary verdict and any escalation vetoes. */
+	verdict(entry, threshold, source, command, escalated) {
+		if (entry.probability < threshold) return {
+			kind: "delegate",
+			reason: `safe probability ${entry.probability.toFixed(3)} below ${threshold}`,
+			probability: entry.probability,
+			command
+		};
+		if (!escalated) return {
 			kind: "approve",
-			probability,
+			probability: entry.probability,
 			source,
 			command
-		} : {
+		};
+		if (entry.escalation === void 0) return {
 			kind: "delegate",
-			reason: `safe probability ${probability.toFixed(3)} below ${threshold}`,
-			probability,
+			reason: "the cached sandbox-escalation verdict was incomplete",
+			command
+		};
+		if (entry.escalation.scope < threshold) return {
+			kind: "delegate",
+			reason: `sandbox scope probability ${entry.escalation.scope.toFixed(3)} below ${threshold}`,
+			probability: entry.probability,
+			command
+		};
+		if (entry.escalation.necessity < threshold) return {
+			kind: "delegate",
+			reason: `sandbox necessity probability ${entry.escalation.necessity.toFixed(3)} below ${threshold}`,
+			probability: entry.probability,
+			command
+		};
+		return {
+			kind: "approve",
+			probability: entry.probability,
+			source,
+			...entry.escalation === void 0 ? {} : { escalation: entry.escalation },
 			command
 		};
 	}
@@ -7986,7 +8073,7 @@ function applyCommandGuard(ctx, deps) {
 			return next();
 		}
 		if (verdict.kind === "approve") {
-			deps.log?.(`command guard auto-approved a ${request.toolName} call (safe probability ${verdict.probability.toFixed(3)}, ${verdict.source}): ${verdict.command ?? "(command unknown)"}`);
+			deps.log?.(`command guard auto-approved a ${request.toolName} call (safe probability ${verdict.probability.toFixed(3)}${verdict.escalation === void 0 ? "" : `, sandbox scope ${verdict.escalation.scope.toFixed(3)}, necessity ${verdict.escalation.necessity.toFixed(3)}`}, ${verdict.source}): ${verdict.command ?? "(command unknown)"}`);
 			return "allowed-once";
 		}
 		deps.log?.(`command guard delegated a ${request.toolName} call: ${verdict.reason}${verdict.command === void 0 ? "" : ` — ${verdict.command}`}`);
@@ -8170,8 +8257,7 @@ const Config = z.object(markVolatileFields({
 		account: z.string()
 	})),
 	commandGuard: z.boolean().default(false),
-	commandGuardThreshold: z.number().min(COMMAND_GUARD_MIN_THRESHOLD).max(1),
-	commandGuardTimeoutMs: z.number().min(200).max(COMMAND_GUARD_MAX_TIMEOUT_MS),
+	commandGuardLevel: z.union([...COMMAND_GUARD_LEVELS]).default(COMMAND_GUARD_DEFAULT_LEVEL),
 	zdr: z.boolean().default(false),
 	lang: z.string().pattern(/^(zh|en)$/).default("zh")
 }, ["apiKey"]));
@@ -8402,8 +8488,8 @@ function apply(ctx, config) {
 		const raw = current();
 		return {
 			enabled: raw.commandGuard === true,
-			threshold: raw.commandGuardThreshold ?? .9,
-			timeoutMs: raw.commandGuardTimeoutMs ?? COMMAND_GUARD_DEFAULT_TIMEOUT_MS
+			threshold: commandGuardThreshold(raw.commandGuardLevel),
+			timeoutMs: COMMAND_GUARD_TIMEOUT_MS
 		};
 	};
 	ctx.inject(["approval"], (approvalCtx) => {