@vellumai/assistant 0.4.54 → 0.4.56

package/src/tools/executor.ts

@@ -1,9 +1,12 @@
 import { readFileSync } from "node:fs";
 
 import { getConfig } from "../config/loader.js";
+import { bridgeCesApproval } from "../credential-execution/approval-bridge.js";
+import { isCesShellLockdownEnabled } from "../credential-execution/feature-gates.js";
 import { getHookManager } from "../hooks/manager.js";
 import { PermissionPrompter } from "../permissions/prompter.js";
 import { RiskLevel } from "../permissions/types.js";
+import { isUntrustedTrustClass } from "../runtime/actor-trust-resolver.js";
 import { redactSensitiveFields } from "../security/redaction.js";
 import { TokenExpiredError } from "../security/token-manager.js";
 import { PermissionDeniedError, ToolError } from "../util/errors.js";
@@ -55,7 +58,6 @@ export class ToolExecutor {
       executionTarget,
       input,
       workingDir: context.workingDir,
-      sessionId: context.sessionId,
       conversationId: context.conversationId,
       requestId: context.requestId,
       startedAtMs: startTime,
@@ -80,10 +82,37 @@ export class ToolExecutor {
     const tool = gateResult.tool;
 
     try {
+      // CES shell lockdown: set forcePromptSideEffects BEFORE both the
+      // grantConsumed short-circuit and the permission check. This ensures
+      // the flag is visible to all downstream consumers regardless of
+      // whether a scoped grant was consumed. Previously this was nested
+      // inside the `!grantConsumed` block, meaning untrusted host_bash
+      // calls that arrived with a consumed guardian-approval grant would
+      // skip this assignment entirely — defeating the lockdown.
+      if (
+        name === "host_bash" &&
+        isCesShellLockdownEnabled(getConfig()) &&
+        isUntrustedTrustClass(context.trustClass)
+      ) {
+        context.forcePromptSideEffects = true;
+      }
+
+      // Secure command tool installation always requires fresh per-invocation
+      // approval — no persistent grants. This is unconditional (not gated on
+      // CES lockdown or trust class) because installing secure tools is
+      // inherently high-impact.
+      if (name === "manage_secure_command_tool") {
+        context.forcePromptSideEffects = true;
+        context.requireFreshApproval = true;
+      }
+
       // A consumed scoped grant is a complete authorization — skip the
       // interactive permission/prompt flow so non-interactive sessions
       // don't auto-deny prompt-gated tools and burn the one-time grant.
-      if (!gateResult.grantConsumed) {
+      // Exception: requireFreshApproval tools always go through the
+      // permission check even when a grant was consumed — the grant does
+      // not substitute for an interactive human review.
+      if (!gateResult.grantConsumed || context.requireFreshApproval) {
         // Check permissions via the extracted PermissionChecker
         const permResult = await this.permissionChecker.checkPermission(
           name,
@@ -111,7 +140,7 @@ export class ToolExecutor {
         riskLevel,
         decision,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
+        conversationId: context.conversationId,
       });
 
       if (hookResult.blocked) {
@@ -123,7 +152,6 @@ export class ToolExecutor {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -176,7 +204,6 @@ export class ToolExecutor {
             executionTarget,
             input,
             workingDir: context.workingDir,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             requestId: context.requestId,
             riskLevel,
@@ -201,6 +228,116 @@ export class ToolExecutor {
         );
       }
 
+      // CES approval bridge: if the tool returned an approval_required
+      // indicator, present the proposal to the guardian via the existing
+      // confirmation transport, commit the decision to CES, and retry
+      // the original tool invocation with the granted grantId.
+      if (execResult.cesApprovalRequired && !context.cesClient) {
+        const msg = `CES approval required for "${name}" but no CES client is available. Ensure the Credential Execution Service is running.`;
+        const durationMs = Date.now() - startTime;
+        emitLifecycleEvent(context, {
+          type: "error",
+          toolName: name,
+          executionTarget,
+          input,
+          workingDir: context.workingDir,
+          conversationId: context.conversationId,
+          requestId: context.requestId,
+          riskLevel,
+          decision: "error",
+          durationMs,
+          errorMessage: msg,
+          isExpected: true,
+          errorCategory: "tool_failure",
+        });
+        return { content: msg, isError: true };
+      }
+      if (execResult.cesApprovalRequired && context.cesClient) {
+        const bridgeResult = await bridgeCesApproval(
+          execResult.cesApprovalRequired,
+          this.prompter,
+          context.cesClient,
+          {
+            isInteractive: context.isInteractive,
+            conversationId: context.conversationId,
+            signal: context.signal,
+          },
+        );
+
+        if (bridgeResult.outcome === "approved") {
+          // Retry the original tool invocation with the grantId attached.
+          // The CES tool implementations accept grantId in the input to
+          // bypass the approval check on the retry.
+          const retryInput = { ...input, grantId: bridgeResult.grantId };
+
+          log.info(
+            {
+              toolName: name,
+              grantId: bridgeResult.grantId,
+              conversationId: context.conversationId,
+            },
+            "CES approval granted — retrying tool invocation with grantId",
+          );
+
+          if (tool.executionMode === "proxy") {
+            execResult = await executeWithTimeout(
+              context.proxyToolResolver!(name, retryInput),
+              toolTimeoutMs,
+              name,
+            );
+          } else {
+            execResult = await executeWithTimeout(
+              tool.execute(retryInput, execContext),
+              toolTimeoutMs,
+              name,
+            );
+          }
+        } else if (
+          bridgeResult.outcome === "denied" ||
+          bridgeResult.outcome === "timeout"
+        ) {
+          const denialReason =
+            bridgeResult.outcome === "timeout"
+              ? `CES approval timed out for "${name}". The tool was not executed.`
+              : `CES approval denied for "${name}". The tool was not executed.`;
+          const durationMs = Date.now() - startTime;
+          emitLifecycleEvent(context, {
+            type: "permission_denied",
+            toolName: name,
+            executionTarget,
+            input,
+            workingDir: context.workingDir,
+            conversationId: context.conversationId,
+            requestId: context.requestId,
+            riskLevel,
+            decision: "deny",
+            reason: denialReason,
+            durationMs,
+          });
+          return { content: denialReason, isError: true };
+        } else {
+          // bridgeResult.outcome === "error"
+          const errorMsg = `CES approval bridge error for "${name}": ${bridgeResult.message}`;
+          const durationMs = Date.now() - startTime;
+          emitLifecycleEvent(context, {
+            type: "error",
+            toolName: name,
+            executionTarget,
+            input,
+            workingDir: context.workingDir,
+            conversationId: context.conversationId,
+            requestId: context.requestId,
+            riskLevel,
+            decision: "error",
+            durationMs,
+            errorMessage: errorMsg,
+            isExpected: true,
+            errorCategory: "tool_failure",
+          });
+          return { content: errorMsg, isError: true };
+        }
+      }
+
       // Sensitive output extraction: strip directives, replace raw values
       // with placeholders, and attach bindings for agent-loop substitution.
       // Runs before secret detection so that raw sensitive values are already
@@ -243,7 +380,6 @@ export class ToolExecutor {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -258,7 +394,7 @@ export class ToolExecutor {
         riskLevel,
         isError: execResult.isError,
         durationMs,
-        sessionId: context.sessionId,
+        conversationId: context.conversationId,
       });
 
       return execResult;
@@ -298,7 +434,6 @@ export class ToolExecutor {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -317,7 +452,7 @@ export class ToolExecutor {
         riskLevel,
         isError: true,
         durationMs,
-        sessionId: context.sessionId,
+        conversationId: context.conversationId,
       });
 
       if (isExpected) {

package/src/tools/followups/followup_create.ts

@@ -7,7 +7,7 @@ function formatFollowUp(f: FollowUp): string {
   const lines = [
     `Follow-up ${f.id}`,
     `  Channel: ${f.channel}`,
-    `  Thread: ${f.threadId}`,
+    `  Conversation: ${f.conversationId}`,
     `  Status: ${f.status}`,
     `  Sent at: ${new Date(f.sentAt).toISOString()}`,
   ];
@@ -34,14 +34,15 @@ export async function executeFollowupCreate(
     };
   }
 
-  const threadId = input.thread_id as string | undefined;
+  const conversationId = input.conversation_id as string | undefined;
   if (
-    !threadId ||
-    typeof threadId !== "string" ||
-    threadId.trim().length === 0
+    !conversationId ||
+    typeof conversationId !== "string" ||
+    conversationId.trim().length === 0
   ) {
     return {
-      content: "Error: thread_id is required and must be a non-empty string",
+      content:
+        "Error: conversation_id is required and must be a non-empty string",
       isError: true,
     };
   }
@@ -81,7 +82,7 @@ export async function executeFollowupCreate(
 
     const followUp = createFollowUp({
       channel: channel.trim(),
-      threadId: threadId.trim(),
+      conversationId: conversationId.trim(),
       contactId: contactId ?? null,
       sentAt: now,
       expectedResponseBy,

package/src/tools/followups/followup_list.ts

@@ -8,7 +8,9 @@ import type { ToolContext, ToolExecutionResult } from "../types.js";
 const VALID_STATUSES = ["pending", "resolved", "overdue", "nudged"] as const;
 
 function formatFollowUpSummary(f: FollowUp): string {
-  const parts = [`- **${f.channel}** thread:${f.threadId} (ID: ${f.id})`];
+  const parts = [
+    `- **${f.channel}** conversation:${f.conversationId} (ID: ${f.id})`,
+  ];
   parts.push(
     `  Status: ${f.status} | Sent: ${new Date(f.sentAt).toISOString()}`,
   );

package/src/tools/followups/followup_resolve.ts

@@ -1,5 +1,5 @@
 import {
-  resolveByThread,
+  resolveByConversation,
   resolveFollowUp,
 } from "../../followups/followup-store.js";
 import type { FollowUp } from "../../followups/types.js";
@@ -9,7 +9,7 @@ function formatFollowUp(f: FollowUp): string {
   const lines = [
     `Follow-up ${f.id}`,
     `  Channel: ${f.channel}`,
-    `  Thread: ${f.threadId}`,
+    `  Conversation: ${f.conversationId}`,
     `  Status: ${f.status}`,
   ];
   if (f.contactId) lines.push(`  Contact ID: ${f.contactId}`);
@@ -22,11 +22,12 @@ export async function executeFollowupResolve(
 ): Promise<ToolExecutionResult> {
   const id = input.id as string | undefined;
   const channel = input.channel as string | undefined;
-  const threadId = input.thread_id as string | undefined;
+  const conversationId = input.conversation_id as string | undefined;
 
-  if (!id && !(channel && threadId)) {
+  if (!id && !(channel && conversationId)) {
     return {
-      content: "Error: Either id or both channel and thread_id are required",
+      content:
+        "Error: Either id or both channel and conversation_id are required",
       isError: true,
     };
   }
@@ -39,10 +40,10 @@ export async function executeFollowupResolve(
         isError: false,
       };
     } else {
-      const resolved = resolveByThread(channel!, threadId!);
+      const resolved = resolveByConversation(channel!, conversationId!);
       if (resolved.length === 0) {
         return {
-          content: `No pending follow-up found for channel="${channel}" thread="${threadId}"`,
+          content: `No pending follow-up found for channel="${channel}" conversation="${conversationId}"`,
           isError: false,
         };
       }

package/src/tools/host-filesystem/edit.ts

@@ -93,7 +93,7 @@ class HostFileEditTool implements Tool {
           new_string: newString as string,
           replace_all: replaceAll,
         },
-        context.sessionId,
+        context.conversationId,
         context.signal,
       );
     }

package/src/tools/host-filesystem/read.ts

@@ -57,7 +57,7 @@ class HostFileReadTool implements Tool {
           offset: typeof input.offset === "number" ? input.offset : undefined,
           limit: typeof input.limit === "number" ? input.limit : undefined,
         },
-        context.sessionId,
+        context.conversationId,
         context.signal,
       );
     }

package/src/tools/host-filesystem/write.ts

@@ -62,7 +62,7 @@ class HostFileWriteTool implements Tool {
           path: rawPath,
           content: fileContent,
         },
-        context.sessionId,
+        context.conversationId,
         context.signal,
       );
     }

package/src/tools/host-terminal/host-shell.ts

@@ -1,11 +1,28 @@
+/**
+ * Host shell tool — `host_bash`.
+ *
+ * Unlike the sandboxed `bash` tool, `host_bash` runs commands directly on the
+ * host machine without the OS-level sandbox. Under CES shell lockdown for
+ * untrusted actors, `host_bash` remains available as a user-approved escape
+ * hatch — the guardian must explicitly approve each invocation. It is NOT part
+ * of the strong CES secrecy guarantee because it runs unsandboxed and could
+ * access protected paths or credential material on disk.
+ *
+ * To mitigate risk, when CES shell lockdown is active for untrusted sessions:
+ * - Persistent approvals are disabled (every invocation requires fresh approval).
+ * - The VELLUM_UNTRUSTED_SHELL=1 env flag is set so CLI commands self-deny
+ *   raw-token/secret reveal flows.
+ */
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute } from "node:path";
 
 import { getConfig } from "../../config/loader.js";
+import { isCesShellLockdownEnabled } from "../../credential-execution/feature-gates.js";
 import { RiskLevel } from "../../permissions/types.js";
 import type { ToolDefinition } from "../../providers/types.js";
+import { isUntrustedTrustClass } from "../../runtime/actor-trust-resolver.js";
 import { redactSecrets } from "../../security/secret-scanner.js";
 import { getLogger } from "../../util/logger.js";
 import { formatShellOutput } from "../shared/shell-output.js";
@@ -33,6 +50,9 @@ class HostShellTool implements Tool {
   name = "host_bash";
   description = "Execute a shell command on the host machine";
   category = "host-terminal";
+  // host_bash is a weaker-tier escape hatch under CES lockdown. It remains
+  // Medium risk by default but persistent approvals are disabled for
+  // untrusted sessions (see execute()).
   defaultRiskLevel = RiskLevel.Medium;
 
   getDefinition(): ToolDefinition {
@@ -101,11 +121,26 @@ class HostShellTool implements Tool {
         isError: true,
       };
     }
+    const config = getConfig();
+    const { shellDefaultTimeoutSec, shellMaxTimeoutSec } = config.timeouts;
+
+    // CES shell lockdown: host_bash is the weaker-tier escape hatch. When
+    // lockdown is active for untrusted actors, persistent approvals are
+    // disabled (every invocation requires fresh guardian approval) and the
+    // VELLUM_UNTRUSTED_SHELL flag is injected to self-deny raw-secret CLI
+    // commands. This does NOT provide the strong CES secrecy guarantee —
+    // the subprocess runs unsandboxed and could access protected paths.
+    //
+    // NOTE: forcePromptSideEffects is set in executor.ts BEFORE the
+    // permission check runs, not here. Setting it here would be too late
+    // because execute() is called after permissions have already been evaluated.
+    const hostLockdownActive =
+      isCesShellLockdownEnabled(config) &&
+      isUntrustedTrustClass(context.trustClass);
+
     // Proxy to connected client for execution on the user's machine
     // when a capable client is available (managed/cloud-hosted mode).
     if (context.hostBashProxy?.isAvailable()) {
-      const { shellDefaultTimeoutSec, shellMaxTimeoutSec } =
-        getConfig().timeouts;
       const rawSec =
         typeof input.timeout_seconds === "number"
           ? input.timeout_seconds
@@ -114,13 +149,19 @@ class HostShellTool implements Tool {
         1,
         Math.min(rawSec, shellMaxTimeoutSec),
       );
+      // Propagate VELLUM_UNTRUSTED_SHELL to the proxied client so CLI
+      // commands self-deny raw-secret flows even when executed remotely.
+      const proxyEnv: Record<string, string> | undefined = hostLockdownActive
+        ? { VELLUM_UNTRUSTED_SHELL: "1" }
+        : undefined;
       return context.hostBashProxy.request(
         {
           command,
           working_dir: rawWorkingDir as string | undefined,
           timeout_seconds: normalizedTimeout,
+          env: proxyEnv,
         },
-        context.sessionId,
+        context.conversationId,
         context.signal,
       );
     }
@@ -128,8 +169,6 @@ class HostShellTool implements Tool {
     const workingDir =
       typeof rawWorkingDir === "string" ? rawWorkingDir : homedir();
 
-    const config = getConfig();
-    const { shellDefaultTimeoutSec, shellMaxTimeoutSec } = config.timeouts;
     const requestedSec =
       typeof input.timeout_seconds === "number"
         ? input.timeout_seconds
@@ -142,7 +181,8 @@ class HostShellTool implements Tool {
         command: redactSecrets(command),
         cwd: workingDir,
         timeoutSec,
-        sessionId: context.sessionId,
+        conversationId: context.conversationId,
+        hostLockdownActive,
       },
       "Executing host shell command",
     );
@@ -152,9 +192,16 @@ class HostShellTool implements Tool {
       const stderrChunks: Buffer[] = [];
       let timedOut = false;
 
+      const hostEnv = buildHostShellEnv();
+      // Inject VELLUM_UNTRUSTED_SHELL=1 so assistant CLI commands self-deny
+      // raw-token/secret reveal flows when invoked from an untrusted shell.
+      if (hostLockdownActive) {
+        hostEnv.VELLUM_UNTRUSTED_SHELL = "1";
+      }
+
       const child = spawn("bash", ["-c", "--", command], {
         cwd: workingDir,
-        env: buildHostShellEnv(),
+        env: hostEnv,
         stdio: ["ignore", "pipe", "pipe"],
       });
 

package/src/tools/memory/definitions.ts

@@ -15,7 +15,7 @@ export const memoryRecallDefinition: ToolDefinition = {
         type: "string",
         enum: ["default", "conversation"],
         description:
-          'Scope to search — "default" searches all memory, "conversation" restricts to current thread',
+          'Scope to search — "default" searches all memory, "conversation" restricts to current conversation',
       },
     },
     required: ["query"],

package/src/tools/memory/handlers.ts

@@ -169,7 +169,7 @@ export async function handleMemoryUpdate(
   try {
     const db = getDb();
 
-    // Constrain lookup to the current scope so threads cannot mutate
+    // Constrain lookup to the current scope so conversations cannot mutate
     // memory items belonging to a different scope.
     const existing = db
       .select()