@vellumai/assistant 0.6.5 → 0.6.6

package/src/permissions/approval-policy.ts

@@ -21,13 +21,23 @@ export interface ApprovalContext {
   isSkillBundled?: boolean;
   /** Whether the tool has a manifest override (unregistered skill tool). */
   hasManifestOverride?: boolean;
+  /** Whether the command's registry entry has sandboxAutoApprove: true. */
+  hasSandboxAutoApprove?: boolean;
   /**
    * Resolved auto-approve threshold for this execution context.
    * - "none": prompt for everything (strictest)
    * - "low": auto-approve Low risk (default, matches existing behavior)
    * - "medium": auto-approve Low and Medium risk
+   * - "high": auto-approve everything unconditionally
    */
-  autoApproveUpTo?: "none" | "low" | "medium";
+  autoApproveUpTo?: "none" | "low" | "medium" | "high";
+  /**
+   * When true, the auto-approve threshold was resolved from the gateway
+   * (permission-controls-v3). This enables threshold-based override of
+   * ask rules — the user's threshold setting takes precedence over
+   * default ask rules when the risk falls within the threshold.
+   */
+  isGatewayThreshold?: boolean;
 }
 
 // ── Threshold resolution ─────────────────────────────────────────────────────
@@ -53,7 +63,10 @@ export interface ApprovalContext {
  * `"low"` is therefore *less strict* than the headless default. This is
  * intentional: the user explicitly chose a uniform threshold.
  */
-const CONTEXT_DEFAULTS: Record<ExecutionContext, "none" | "low" | "medium"> = {
+const CONTEXT_DEFAULTS: Record<
+  ExecutionContext,
+  "none" | "low" | "medium" | "high"
+> = {
   conversation: "low",
   background: "medium",
   headless: "none",
@@ -62,7 +75,7 @@ const CONTEXT_DEFAULTS: Record<ExecutionContext, "none" | "low" | "medium"> = {
 export function resolveThreshold(
   configValue: PermissionsConfig["autoApproveUpTo"] | undefined,
   executionContext?: ExecutionContext,
-): "none" | "low" | "medium" {
+): "none" | "low" | "medium" | "high" {
   if (configValue == null) {
     return CONTEXT_DEFAULTS[executionContext ?? "conversation"];
   }
@@ -82,8 +95,22 @@ const THRESHOLD_ORDINAL: Record<string, number> = {
   none: -1,
   low: 0,
   medium: 1,
+  high: 2,
 };
 
+/**
+ * Check whether a risk level falls within the configured auto-approve threshold.
+ * Returns `true` when the risk is at or below the threshold (i.e. auto-approve).
+ */
+function isRiskWithinThreshold(
+  riskLevel: string,
+  autoApproveUpTo: string | undefined,
+): boolean {
+  const risk = RISK_ORDINAL[riskLevel] ?? 2;
+  const threshold = THRESHOLD_ORDINAL[autoApproveUpTo ?? "low"] ?? 0;
+  return risk <= threshold;
+}
+
 /** The outcome of an approval policy evaluation. */
 export interface ApprovalDecision {
   decision: "allow" | "prompt" | "deny";
@@ -105,14 +132,20 @@ export interface ApprovalPolicy {
  * The decision flow:
  *
  * 1. Deny rule → deny
- * 2. Ask rule → prompt
- * 3. Allow rule + non-High → allow
- * 4. Allow rule + High + containerized bash → allow (shouldAutoAllowHighRisk)
- * 5. Allow rule + High + no auto-allow → prompt (fall through)
- * 6. No rule + third-party skill tool → prompt
- * 7. No rule + strict mode → prompt
+ * 2. Ask rule + risk > autoApproveUpTo → prompt
+ *    Ask rule + risk ≤ autoApproveUpTo → allow (v3 only: threshold overrides ask)
+ *    Exception: skill_load_dynamic ask rules always prompt (inline-command safety gate)
+ * 3. Sandbox auto-approve: workspace mode + bash + sandboxAutoApprove → allow
+ *    (Path resolution is baked into `hasSandboxAutoApprove` upstream: containerized
+ *    environments skip path checks; non-containerized environments validate all
+ *    path arguments against the workspace root.)
+ * 4. Allow rule + non-High → allow
+ * 5. Allow rule + High → fall through to risk-based
+ * 6. No rule + third-party skill tool + risk > autoApproveUpTo → prompt
+ *    No rule + third-party skill tool + risk ≤ autoApproveUpTo → allow (v3 only)
+ * 7. No rule + strict mode + risk > autoApproveUpTo → prompt
+ *    No rule + strict mode + risk ≤ autoApproveUpTo → allow (v3 only)
  * 8. No rule + workspace mode + Low + workspace-scoped → allow
- *    (except non-containerized bash — never auto-allow)
  * 9. No rule + Low + bundled skill → allow
  * 10. Risk ≤ autoApproveUpTo threshold → allow
  * 11. Risk > autoApproveUpTo threshold → prompt
@@ -124,11 +157,11 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
       toolName,
       matchedRule,
       permissionsMode,
-      isContainerized,
       isWorkspaceScoped,
       toolOrigin,
       isSkillBundled,
       hasManifestOverride,
+      hasSandboxAutoApprove,
     } = context;
 
     // ── 1. Deny rules apply at ALL risk levels ────────────────────────
@@ -140,8 +173,29 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
       };
     }
 
-    // ── 2. Ask rules always prompt ────────────────────────────────────
+    // ── 2. Ask rules prompt — unless the gateway threshold covers the risk.
+    // When permission-controls-v3 is active (isGatewayThreshold), the user's
+    // threshold setting takes precedence over ask rules: if the risk falls
+    // within autoApproveUpTo, the ask rule is overridden and the tool
+    // auto-approves. Without v3, ask rules always prompt (preserving
+    // backward-compatible behavior for default ask rules on host tools, etc.).
+    // Exception: skill_load_dynamic ask rules always prompt — they gate
+    // inline-command skill loads that execute embedded commands and must
+    // never be silently auto-approved.
     if (matchedRule && matchedRule.decision === "ask") {
+      const isDynamicSkillAsk = matchedRule.pattern.startsWith(
+        "skill_load_dynamic:",
+      );
+      if (
+        !isDynamicSkillAsk &&
+        context.isGatewayThreshold &&
+        isRiskWithinThreshold(riskLevel, context.autoApproveUpTo)
+      ) {
+        return {
+          decision: "allow",
+          reason: `${riskLevel} risk: within auto-approve threshold (ask rule overridden)`,
+        };
+      }
       return {
         decision: "prompt",
         reason: `Matched ask rule: ${matchedRule.pattern}`,
@@ -149,9 +203,24 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
       };
     }
 
-    // ── 3–5. Allow rule handling ──────────────────────────────────────
+    // ── 3. Sandbox auto-approve: bash + allowlisted → allow ──
+    // Only fires in workspace mode — strict mode always requires explicit rules.
+    // Path resolution is baked into `hasSandboxAutoApprove` upstream:
+    // containerized environments skip path checks (entire fs is workspace),
+    // non-containerized environments validate all path args against workspace root.
+    if (
+      permissionsMode === "workspace" &&
+      toolName === "bash" &&
+      hasSandboxAutoApprove === true
+    ) {
+      return {
+        decision: "allow",
+        reason: "Workspace filesystem operation (sandbox auto-approve)",
+      };
+    }
+
+    // ── 4–5. Allow rule handling ──────────────────────────────────────
     if (matchedRule) {
-      // 3. Allow rule + non-High → allow
       if (riskLevel !== RiskLevel.High) {
         return {
           decision: "allow",
@@ -159,30 +228,24 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
           matchedRule,
         };
       }
-
-      // 4. Allow rule + High + containerized bash → allow
-      if (this.shouldAutoAllowHighRisk(toolName, isContainerized)) {
-        return {
-          decision: "allow",
-          reason: `Matched trust rule in auto-allow-high-risk context: ${matchedRule.pattern}`,
-          matchedRule,
-        };
-      }
-
-      // 5. Allow rule + High (no auto-allow) → fall through to risk-based
-      // Note: matchedRule is intentionally omitted from the risk-based
-      // fallback return — the decision is driven by risk, not the rule.
+      // High risk: fall through to risk-based regardless of rule
     }
 
-    // ── 6. No rule + third-party skill tool → prompt ──────────────────
+    // ── 6. No rule + third-party skill tool → prompt (unless v3 threshold covers it)
     if (!matchedRule) {
-      if (toolOrigin === "skill" && !isSkillBundled) {
-        return {
-          decision: "prompt",
-          reason: "Skill tool: requires approval by default",
-        };
-      }
-      if (hasManifestOverride && !toolOrigin) {
+      const isThirdPartySkill =
+        (toolOrigin === "skill" && !isSkillBundled) ||
+        (hasManifestOverride && !toolOrigin);
+      if (isThirdPartySkill) {
+        if (
+          context.isGatewayThreshold &&
+          isRiskWithinThreshold(riskLevel, context.autoApproveUpTo)
+        ) {
+          return {
+            decision: "allow",
+            reason: `${riskLevel} risk: within auto-approve threshold (skill tool)`,
+          };
+        }
         return {
           decision: "prompt",
           reason: "Skill tool: requires approval by default",
@@ -190,8 +253,17 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
       }
     }
 
-    // ── 7. No rule + strict mode → prompt ─────────────────────────────
+    // ── 7. No rule + strict mode → prompt (unless v3 threshold covers it)
     if (permissionsMode === "strict" && !matchedRule) {
+      if (
+        context.isGatewayThreshold &&
+        isRiskWithinThreshold(riskLevel, context.autoApproveUpTo)
+      ) {
+        return {
+          decision: "allow",
+          reason: `${riskLevel} risk: within auto-approve threshold (strict mode overridden)`,
+        };
+      }
       return {
         decision: "prompt",
         reason: "Strict mode: no matching rule, requires approval",
@@ -199,15 +271,12 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
     }
 
     // ── 8. No rule + workspace mode + Low + workspace-scoped → allow ──
-    // Exception: non-containerized bash never auto-allows.
     if (
       permissionsMode === "workspace" &&
       !matchedRule &&
       riskLevel === RiskLevel.Low
     ) {
-      if (toolName === "bash" && !isContainerized) {
-        // Fall through to risk-based policy below
-      } else if (isWorkspaceScoped) {
+      if (isWorkspaceScoped) {
         return {
           decision: "allow",
           reason: "Workspace mode: workspace-scoped operation auto-allowed",
@@ -226,10 +295,7 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
     }
 
     // ── 10–11. Risk-based fallback: compare risk against configured threshold ─
-    const autoApproveUpTo = context.autoApproveUpTo ?? "low";
-    const risk = RISK_ORDINAL[riskLevel] ?? 2;
-    const threshold = THRESHOLD_ORDINAL[autoApproveUpTo] ?? 0;
-    if (risk <= threshold) {
+    if (isRiskWithinThreshold(riskLevel, context.autoApproveUpTo)) {
       return {
         decision: "allow",
         reason: `${riskLevel} risk: within auto-approve threshold`,
@@ -240,18 +306,4 @@ export class DefaultApprovalPolicy implements ApprovalPolicy {
       reason: `${riskLevel} risk: above auto-approve threshold`,
     };
   }
-
-  /**
-   * Determines at runtime whether a high-risk operation should be auto-allowed.
-   * Auto-allows high-risk operations when running in a containerized sandbox.
-   *
-   * Auto-allow cases:
-   * - Containerized bash: all commands are sandboxed, so high-risk is safe.
-   */
-  private shouldAutoAllowHighRisk(
-    toolName: string,
-    isContainerized: boolean,
-  ): boolean {
-    return toolName === "bash" && isContainerized;
-  }
 }

package/src/permissions/arg-parser.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, test } from "bun:test";
+
+import { parseArgs } from "./arg-parser.js";
+
+describe("parseArgs", () => {
+  test("boolean flags", () => {
+    const result = parseArgs(["-v", "-f"], {});
+    expect(result.flags.get("-v")).toBe(true);
+    expect(result.flags.get("-f")).toBe(true);
+    expect(result.positionals).toEqual([]);
+    expect(result.pathArgs).toEqual([]);
+    expect(result.sawDoubleDash).toBe(false);
+  });
+
+  test("value-consuming flags", () => {
+    const result = parseArgs(["-o", "out.txt", "in.txt"], {
+      valueFlags: ["-o"],
+    });
+    expect(result.flags.get("-o")).toBe("out.txt");
+    expect(result.positionals).toEqual(["in.txt"]);
+    // Default positionals mode is "paths", so in.txt is a path.
+    expect(result.pathArgs).toEqual(["in.txt"]);
+  });
+
+  test("path flags", () => {
+    const result = parseArgs(["-t", "/tmp/dir", "file.txt"], {
+      valueFlags: ["-t"],
+      pathFlags: { "-t": true },
+    });
+    expect(result.flags.get("-t")).toBe("/tmp/dir");
+    expect(result.positionals).toEqual(["file.txt"]);
+    // /tmp/dir from pathFlag + file.txt from default positional "paths" mode.
+    expect(result.pathArgs).toEqual(["/tmp/dir", "file.txt"]);
+  });
+
+  test("-- terminator", () => {
+    const result = parseArgs(["--", "-notaflag"], {});
+    expect(result.sawDoubleDash).toBe(true);
+    expect(result.positionals).toEqual(["-notaflag"]);
+    expect(result.pathArgs).toEqual(["-notaflag"]);
+    expect(result.flags.size).toBe(0);
+  });
+
+  test("respectsDoubleDash: false", () => {
+    const result = parseArgs(["--", "-notaflag"], {
+      respectsDoubleDash: false,
+    });
+    // `--` is treated as a boolean flag, not a terminator.
+    expect(result.sawDoubleDash).toBe(false);
+    expect(result.flags.get("--")).toBe(true);
+    expect(result.flags.get("-notaflag")).toBe(true);
+    expect(result.positionals).toEqual([]);
+  });
+
+  test("positionals 'paths' (default) — all positionals in pathArgs", () => {
+    const result = parseArgs(["a.txt", "b.txt"], {});
+    expect(result.positionals).toEqual(["a.txt", "b.txt"]);
+    expect(result.pathArgs).toEqual(["a.txt", "b.txt"]);
+  });
+
+  test("positionals 'paths' (explicit) — all positionals in pathArgs", () => {
+    const result = parseArgs(["a.txt", "b.txt"], { positionals: "paths" });
+    expect(result.positionals).toEqual(["a.txt", "b.txt"]);
+    expect(result.pathArgs).toEqual(["a.txt", "b.txt"]);
+  });
+
+  test("positionals 'none' — no positionals in pathArgs", () => {
+    const result = parseArgs(["a.txt", "b.txt"], { positionals: "none" });
+    expect(result.positionals).toEqual(["a.txt", "b.txt"]);
+    expect(result.pathArgs).toEqual([]);
+  });
+
+  test("mixed positionals (array) with rest descriptor", () => {
+    const result = parseArgs(["pattern", "file1.txt", "file2.txt"], {
+      positionals: [{ role: "pattern" }, { role: "path", rest: true }],
+    });
+    expect(result.positionals).toEqual(["pattern", "file1.txt", "file2.txt"]);
+    // "pattern" has role "pattern" → not a path.
+    // "file1.txt" at index 1 has role "path" with rest → path.
+    // "file2.txt" at index 2 exceeds array but rest descriptor applies → path.
+    expect(result.pathArgs).toEqual(["file1.txt", "file2.txt"]);
+  });
+
+  test("positional array without rest — excess positionals default to path", () => {
+    const result = parseArgs(["script", "extra1", "extra2"], {
+      positionals: [{ role: "script" }],
+    });
+    expect(result.positionals).toEqual(["script", "extra1", "extra2"]);
+    // "script" → role "script" → not a path.
+    // "extra1", "extra2" → no descriptor, no rest → conservative default → path.
+    expect(result.pathArgs).toEqual(["extra1", "extra2"]);
+  });
+
+  test("empty args", () => {
+    const result = parseArgs([], {});
+    expect(result.flags.size).toBe(0);
+    expect(result.positionals).toEqual([]);
+    expect(result.pathArgs).toEqual([]);
+    expect(result.sawDoubleDash).toBe(false);
+  });
+
+  test("value-consuming flag at end of args with no next token — treated as boolean", () => {
+    const result = parseArgs(["-o"], { valueFlags: ["-o"] });
+    expect(result.flags.get("-o")).toBe(true);
+    expect(result.positionals).toEqual([]);
+    expect(result.pathArgs).toEqual([]);
+  });
+
+  test("positionals after -- are still classified by positional descriptors", () => {
+    const result = parseArgs(["--", "pattern", "file.txt"], {
+      positionals: [{ role: "pattern" }, { role: "path" }],
+    });
+    expect(result.sawDoubleDash).toBe(true);
+    expect(result.positionals).toEqual(["pattern", "file.txt"]);
+    // "pattern" at index 0 → role "pattern" → not a path.
+    // "file.txt" at index 1 → role "path" → path.
+    expect(result.pathArgs).toEqual(["file.txt"]);
+  });
+
+  test("value flag value is not added to pathArgs unless flag is in pathFlags", () => {
+    const result = parseArgs(["-o", "/some/path"], {
+      valueFlags: ["-o"],
+      positionals: "none",
+    });
+    expect(result.flags.get("-o")).toBe("/some/path");
+    // -o is not in pathFlags, so the value is not a path.
+    expect(result.pathArgs).toEqual([]);
+  });
+
+  test("multiple path flags accumulate in pathArgs", () => {
+    const result = parseArgs(["-I", "/include1", "-I", "/include2", "src.c"], {
+      valueFlags: ["-I"],
+      pathFlags: { "-I": true },
+    });
+    expect(result.flags.get("-I")).toBe("/include2"); // last value wins in Map
+    expect(result.positionals).toEqual(["src.c"]);
+    expect(result.pathArgs).toEqual(["/include1", "/include2", "src.c"]);
+  });
+
+  test("--flag=value syntax with path flag", () => {
+    const result = parseArgs(["--target-directory=/tmp/dir", "file.txt"], {
+      valueFlags: ["--target-directory"],
+      pathFlags: { "--target-directory": true },
+    });
+    expect(result.flags.get("--target-directory")).toBe("/tmp/dir");
+    expect(result.positionals).toEqual(["file.txt"]);
+    // /tmp/dir from pathFlag + file.txt from default positional "paths" mode.
+    expect(result.pathArgs).toEqual(["/tmp/dir", "file.txt"]);
+  });
+
+  test("--flag=value syntax with non-path value flag", () => {
+    const result = parseArgs(["--output=out.txt", "in.txt"], {
+      valueFlags: ["--output"],
+    });
+    expect(result.flags.get("--output")).toBe("out.txt");
+    expect(result.positionals).toEqual(["in.txt"]);
+    // --output is not in pathFlags, so out.txt is not a path arg.
+    // in.txt is a positional with default "paths" mode → path.
+    expect(result.pathArgs).toEqual(["in.txt"]);
+  });
+});

package/src/permissions/arg-parser.ts

@@ -0,0 +1,141 @@
+import type { ArgSchema, ParsedArgs, PositionalDesc } from "./risk-types.js";
+
+/**
+ * Parse a command's arguments according to an {@link ArgSchema}.
+ *
+ * Classifies each token as a flag, positional, or path argument. The
+ * resulting {@link ParsedArgs} is consumed by downstream path-resolution
+ * and sandbox-policy checks.
+ */
+export function parseArgs(args: string[], schema: ArgSchema): ParsedArgs {
+  const valueFlagSet = new Set(schema.valueFlags);
+  const pathFlagSet = new Set(
+    schema.pathFlags ? Object.keys(schema.pathFlags) : [],
+  );
+
+  const flags = new Map<string, string | true>();
+  const positionals: string[] = [];
+  const pathArgs: string[] = [];
+  let sawDoubleDash = false;
+
+  let i = 0;
+  while (i < args.length) {
+    const token = args[i]!;
+
+    // After `--`, everything is positional.
+    if (sawDoubleDash) {
+      positionals.push(token);
+      addIfPath(token, positionals.length - 1, schema.positionals, pathArgs);
+      i++;
+      continue;
+    }
+
+    // Double-dash terminator.
+    if (token === "--" && schema.respectsDoubleDash !== false) {
+      sawDoubleDash = true;
+      i++;
+      continue;
+    }
+
+    // Value-consuming flag: consume next token as the flag's value.
+    if (token.startsWith("-") && valueFlagSet.has(token)) {
+      const nextIndex = i + 1;
+      if (nextIndex < args.length) {
+        const value = args[nextIndex]!;
+        flags.set(token, value);
+        if (pathFlagSet.has(token)) {
+          pathArgs.push(value);
+        }
+        i += 2;
+      } else {
+        // Flag at end of args with no next token — treat as boolean.
+        flags.set(token, true);
+        i++;
+      }
+      continue;
+    }
+
+    // --flag=value form: split on the first `=` and check if the flag
+    // name is a value-consuming flag. This handles e.g.
+    // `--target-directory=/tmp/` or `--output=out.txt`.
+    if (token.startsWith("-") && token.includes("=")) {
+      const eqIndex = token.indexOf("=");
+      const flagName = token.slice(0, eqIndex);
+      const flagValue = token.slice(eqIndex + 1);
+
+      if (valueFlagSet.has(flagName)) {
+        flags.set(flagName, flagValue);
+        if (pathFlagSet.has(flagName)) {
+          pathArgs.push(flagValue);
+        }
+        i++;
+        continue;
+      }
+    }
+
+    // Boolean flag (starts with `-` but not a value-consuming flag).
+    if (token.startsWith("-")) {
+      flags.set(token, true);
+      i++;
+      continue;
+    }
+
+    // Positional argument.
+    positionals.push(token);
+    addIfPath(token, positionals.length - 1, schema.positionals, pathArgs);
+    i++;
+  }
+
+  return { flags, positionals, pathArgs, sawDoubleDash };
+}
+
+/**
+ * Determine whether a positional at the given index is a path and, if so,
+ * add it to `pathArgs`.
+ */
+function addIfPath(
+  token: string,
+  index: number,
+  positionalsDef: ArgSchema["positionals"],
+  pathArgs: string[],
+): void {
+  if (positionalsDef === undefined || positionalsDef === "paths") {
+    // Default: all positionals are paths.
+    pathArgs.push(token);
+    return;
+  }
+
+  if (positionalsDef === "none") {
+    // Explicitly not paths.
+    return;
+  }
+
+  // Array of PositionalDesc — look up by index.
+  const descs: PositionalDesc[] = positionalsDef;
+
+  // Find the applicable descriptor: either the one at this index, or a
+  // previous `rest: true` descriptor that covers all subsequent positions.
+  let desc: PositionalDesc | undefined;
+
+  if (index < descs.length) {
+    desc = descs[index];
+  } else {
+    // Look backwards for the last `rest: true` descriptor.
+    for (let j = descs.length - 1; j >= 0; j--) {
+      if (descs[j]!.rest) {
+        desc = descs[j];
+        break;
+      }
+    }
+  }
+
+  if (desc) {
+    if (desc.role === "path") {
+      pathArgs.push(token);
+    }
+    // Other roles (pattern, script, value, command) → not a path.
+  } else {
+    // No descriptor and no rest — conservative default: treat as path.
+    pathArgs.push(token);
+  }
+}