@vellumai/assistant 0.4.54 → 0.4.56

package/src/tools/system/avatar-generator.ts

@@ -4,103 +4,76 @@ import { dirname, join } from "node:path";
 
 import { generateAvatar } from "../../media/avatar-router.js";
 import { mapGeminiError } from "../../media/gemini-image-service.js";
-import { RiskLevel } from "../../permissions/types.js";
-import type { ToolDefinition } from "../../providers/types.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspaceDir } from "../../util/platform.js";
-import type { Tool, ToolContext, ToolExecutionResult } from "../types.js";
 
 const log = getLogger("avatar-generator");
 
-const TOOL_NAME = "set_avatar";
-
 /** Canonical path where the custom avatar PNG is stored. */
 function getAvatarPath(): string {
-  return join(getWorkspaceDir(), "data", "avatar", "custom-avatar.png");
+  return join(getWorkspaceDir(), "data", "avatar", "avatar-image.png");
 }
 
-export const setAvatarTool: Tool = {
-  name: TOOL_NAME,
-  description:
-    "Generate a custom avatar image from a text description. " +
-    "Saves the result as the assistant's avatar.",
-  category: "system",
-  defaultRiskLevel: RiskLevel.Low,
+export interface AvatarGenerationResult {
+  content: string;
+  isError: boolean;
+}
 
-  getDefinition(): ToolDefinition {
+/**
+ * Generate a custom avatar image from a text description and save it
+ * as the assistant's avatar PNG.
+ *
+ * Used by the HTTP route handler at POST /v1/settings/avatar/generate.
+ */
+export async function generateAndSaveAvatar(
+  description: string,
+): Promise<AvatarGenerationResult> {
+  if (typeof description !== "string" || description.trim() === "") {
     return {
-      name: TOOL_NAME,
-      description: this.description,
-      input_schema: {
-        type: "object",
-        properties: {
-          description: {
-            type: "string",
-            description:
-              "A text description of the desired avatar appearance, " +
-              'e.g. "a friendly purple cat with green eyes wearing a tiny hat".',
-          },
-        },
-        required: ["description"],
-      },
+      content: "Error: description is required and must be a non-empty string.",
+      isError: true,
     };
-  },
+  }
+
+  try {
+    log.info({ description: description.trim() }, "Generating avatar");
 
-  async execute(
-    input: Record<string, unknown>,
-    _context: ToolContext,
-  ): Promise<ToolExecutionResult> {
-    const description = input.description;
-    if (typeof description !== "string" || description.trim() === "") {
+    const prompt =
+      `Create an avatar image based on this description: ${description.trim()}\n\n` +
+      "Style: cute, friendly, work-safe illustration. " +
+      "Vibrant but soft colors. Simple and recognizable at small sizes (28px). " +
+      "Circular or rounded composition filling the canvas. " +
+      "Subtle background color (not white or transparent).";
+
+    const result = await generateAvatar(prompt);
+    if (!result.imageBase64) {
       return {
-        content:
-          "Error: description is required and must be a non-empty string.",
+        content: "Error: No image data returned. Please try again.",
         isError: true,
       };
     }
+    const pngBuffer = Buffer.from(result.imageBase64, "base64");
 
-    try {
-      log.info({ description: description.trim() }, "Generating avatar");
-
-      const prompt =
-        `Create an avatar image based on this description: ${description.trim()}\n\n` +
-        "Style: cute, friendly, work-safe illustration. " +
-        "Vibrant but soft colors. Simple and recognizable at small sizes (28px). " +
-        "Circular or rounded composition filling the canvas. " +
-        "Subtle background color (not white or transparent).";
+    const avatarPath = getAvatarPath();
+    const avatarDir = dirname(avatarPath);
 
-      const result = await generateAvatar(prompt);
-      if (!result.imageBase64) {
-        return {
-          content: "Error: No image data returned. Please try again.",
-          isError: true,
-        };
-      }
-      const pngBuffer = Buffer.from(result.imageBase64, "base64");
+    const tmpPath = `${avatarPath}.${randomUUID()}.tmp`;
+    mkdirSync(avatarDir, { recursive: true });
+    writeFileSync(tmpPath, pngBuffer);
+    renameSync(tmpPath, avatarPath);
 
-      const avatarPath = getAvatarPath();
-      const avatarDir = dirname(avatarPath);
+    log.info({ avatarPath }, "Avatar saved successfully");
 
-      const tmpPath = `${avatarPath}.${randomUUID()}.tmp`;
-      mkdirSync(avatarDir, { recursive: true });
-      writeFileSync(tmpPath, pngBuffer);
-      renameSync(tmpPath, avatarPath);
-
-      log.info({ avatarPath }, "Avatar saved successfully");
-
-      // Side-effect hook in tool-side-effects.ts broadcasts avatar_updated to all clients.
-
-      return {
-        content: "Avatar updated! Your new avatar will appear shortly.",
-        isError: false,
-      };
-    } catch (error) {
-      const message = mapGeminiError(error);
-      log.error({ error: message }, "Avatar generation failed");
-      return {
-        content: `Avatar generation failed: ${message}`,
-        isError: true,
-      };
-    }
-  },
-};
+    return {
+      content: "Avatar updated! Your new avatar will appear shortly.",
+      isError: false,
+    };
+  } catch (error) {
+    const message = mapGeminiError(error);
+    log.error({ error: message }, "Avatar generation failed");
+    return {
+      content: `Avatar generation failed: ${message}`,
+      isError: true,
+    };
+  }
+}

package/src/tools/terminal/backends/native.ts

@@ -21,24 +21,45 @@ const HASH_DISPLAY_LENGTH = 12;
  * - Allows write access only to the working directory and temp dirs
  * - Blocks outbound network access (unless proxied)
  * - Blocks process debugging (ptrace)
+ * - Optionally blocks read access to specific protected paths (CES lockdown)
  *
  * When `allowNetwork` is true the `(deny network*)` rule is replaced with
  * `(allow network*)` so the process can reach the local credential proxy.
  */
-function buildSandboxProfile(allowNetwork: boolean): string {
+function buildSandboxProfile(
+  allowNetwork: boolean,
+  denyReadPaths?: string[],
+): string {
   const networkRule = allowNetwork
     ? ";; Allow network access (proxied mode — needed to reach the credential proxy)\n(allow network*)"
     : ";; Block network access\n(deny network*)";
 
+  // Build deny-read rules for protected paths (CES shell lockdown).
+  // These are placed AFTER the allow file-read* rule because SBPL uses
+  // last-match-wins semantics — the more specific deny overrides the
+  // general allow.
+  const denyReadRules =
+    denyReadPaths && denyReadPaths.length > 0
+      ? "\n;; CES shell lockdown: block reads of protected credential/transport paths\n" +
+        denyReadPaths
+          .map(
+            (p) =>
+              `(deny file-read* (subpath "${escapeSBPL(p)}") (with no-log))`,
+          )
+          .join("\n")
+      : "";
+
   return `
 (version 1)
 (deny default)
 
 ;; Allow read access to the filesystem (tools, libraries, etc.)
 (allow file-read*)
+${denyReadRules}
 
 ;; Allow write access to the working directory and its children
 (allow file-write*
+  (literal "/dev/null")
   (subpath "__WORKING_DIR__")
   (subpath "/private/tmp")
   (subpath "/tmp")
@@ -90,21 +111,28 @@ function escapeSBPL(path: string): string {
  * a hash of the path) to avoid race conditions when concurrent commands
  * use different working directories.
  */
-function getProfilePath(workingDir: string, allowNetwork: boolean): string {
+function getProfilePath(
+  workingDir: string,
+  allowNetwork: boolean,
+  denyReadPaths?: string[],
+): string {
   const dir = join(process.env.HOME ?? "/tmp", ".vellum");
   if (!existsSync(dir)) {
     mkdirSync(dir, { recursive: true });
   }
-  // Include the network flag in the hash so proxied and non-proxied profiles
-  // for the same directory don't collide.
-  const hashInput = allowNetwork ? `${workingDir}:proxied` : workingDir;
+  // Include the network flag and deny-read paths in the hash so profiles
+  // with different configurations don't collide.
+  let hashInput = allowNetwork ? `${workingDir}:proxied` : workingDir;
+  if (denyReadPaths && denyReadPaths.length > 0) {
+    hashInput += `:deny-read:${denyReadPaths.sort().join(",")}`;
+  }
   const hash = createHash("sha256")
     .update(hashInput)
     .digest("hex")
     .slice(0, HASH_DISPLAY_LENGTH);
   const path = join(dir, `sandbox-profile-${hash}.sb`);
 
-  const profile = buildSandboxProfile(allowNetwork).replace(
+  const profile = buildSandboxProfile(allowNetwork, denyReadPaths).replace(
     /__WORKING_DIR__/g,
     () => escapeSBPL(workingDir),
   );
@@ -155,11 +183,13 @@ function isBwrapAvailable(): boolean {
  * - /dev bind-mounted for device access (needed by many tools)
  * - Network access blocked (--unshare-net)
  * - PID namespace isolated (--unshare-pid)
+ * - Optional tmpfs overlays on protected paths (CES lockdown)
  */
 function buildBwrapArgs(
   workingDir: string,
   command: string,
   allowNetwork: boolean,
+  denyReadPaths?: string[],
 ): string[] {
   const args = [
     // Filesystem: read-only root, writable working dir and temp
@@ -178,6 +208,15 @@ function buildBwrapArgs(
     "/proc",
   ];
 
+  // CES shell lockdown: overlay protected paths with empty tmpfs mounts
+  // so the subprocess cannot read credential data, bootstrap sockets, or
+  // toolstore contents. The tmpfs mount hides the real directory contents.
+  if (denyReadPaths && denyReadPaths.length > 0) {
+    for (const p of denyReadPaths) {
+      args.push("--tmpfs", p);
+    }
+  }
+
   // Only isolate the network namespace when network access is not needed.
   // In proxied mode the process must be able to reach 127.0.0.1:<proxy-port>.
   if (!allowNetwork) {
@@ -207,9 +246,10 @@ export class NativeBackend implements SandboxBackend {
     options?: WrapOptions,
   ): SandboxResult {
     const allowNetwork = options?.networkMode === "proxied";
+    const denyReadPaths = options?.denyReadPaths;
 
     if (isMacOS()) {
-      const profile = getProfilePath(workingDir, allowNetwork);
+      const profile = getProfilePath(workingDir, allowNetwork, denyReadPaths);
       return {
         command: "sandbox-exec",
         args: ["-f", profile, "bash", "-c", "--", command],
@@ -226,7 +266,7 @@ export class NativeBackend implements SandboxBackend {
       }
       return {
         command: "bwrap",
-        args: buildBwrapArgs(workingDir, command, allowNetwork),
+        args: buildBwrapArgs(workingDir, command, allowNetwork, denyReadPaths),
         sandboxed: true,
       };
     }

package/src/tools/terminal/backends/types.ts

@@ -14,6 +14,13 @@ export interface WrapOptions {
    * - 'proxied': network access is allowed so the process can reach the local credential proxy.
    */
   networkMode?: "off" | "proxied";
+
+  /**
+   * Absolute paths that should be blocked from read access inside the sandbox.
+   * Used by CES shell lockdown to prevent untrusted shell commands from reading
+   * protected credential data, bootstrap sockets, and toolstore paths.
+   */
+  denyReadPaths?: string[];
 }
 
 /**

package/src/tools/terminal/safe-env.ts

@@ -6,7 +6,7 @@
  * Shared by the sandbox bash tool and skill sandbox runner.
  */
 import { getGatewayInternalBaseUrl } from "../../config/env.js";
-import { getDataDir } from "../../util/platform.js";
+import { getDataDir, getWorkspaceDir } from "../../util/platform.js";
 
 const SAFE_ENV_VARS = [
   "PATH",
@@ -43,5 +43,8 @@ export function buildSanitizedEnv(): Record<string, string> {
   // Expose the runtime data directory so child processes can locate databases,
   // logs, and other instance-scoped state without re-deriving the path.
   env.VELLUM_DATA_DIR = getDataDir();
+  // Expose the workspace directory so skills and child processes can read/write
+  // workspace-scoped files (e.g. avatar traits, user data).
+  env.VELLUM_WORKSPACE_DIR = getWorkspaceDir();
   return env;
 }

package/src/tools/terminal/shell.ts

@@ -1,11 +1,14 @@
 import { spawn } from "node:child_process";
+import { dirname } 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 { getDataDir } from "../../util/platform.js";
+import { getDataDir, getRootDir } from "../../util/platform.js";
 import { resolveCredentialRef } from "../credentials/resolve.js";
 import {
   getOrStartSession,
@@ -31,6 +34,53 @@ function buildCredentialRefTrace(
   return { rawRefs, resolvedIds, unresolvedRefs };
 }
 
+/**
+ * Build the list of absolute paths that should be blocked from read access
+ * inside the sandbox when CES shell lockdown is active.
+ *
+ * Protected paths include:
+ * - ~/.vellum/protected/ — credential store secrets (also covers local-mode
+ *   CES data root at ~/.vellum/protected/credential-executor/)
+ * - ~/.vellum/workspace/data/db/ — database files that may contain credential metadata
+ * - CES bootstrap socket directory (/run/ces-bootstrap/ or CES_BOOTSTRAP_SOCKET_DIR) —
+ *   prevents untrusted shells from connecting to the CES sidecar directly
+ * - CES managed-mode data root (CES_DATA_DIR, or /ces-data when
+ *   CES_MANAGED_MODE is set) — prevents access to CES-private state in
+ *   managed deployments (local-mode is already covered by the protected/
+ *   entry)
+ */
+function buildCesProtectedPaths(): string[] {
+  const root = getRootDir();
+  const paths = [`${root}/protected`, `${root}/workspace/data/db`];
+
+  // CES bootstrap socket directory — block access to the Unix socket that
+  // accepts RPC commands from the assistant process.
+  const bootstrapSocketDir =
+    process.env["CES_BOOTSTRAP_SOCKET_DIR"] || "/run/ces-bootstrap";
+  paths.push(bootstrapSocketDir);
+
+  // If a full socket path override is set (without the dir env var), block
+  // its parent directory as well.
+  if (
+    !process.env["CES_BOOTSTRAP_SOCKET_DIR"] &&
+    process.env["CES_BOOTSTRAP_SOCKET"]
+  ) {
+    paths.push(dirname(process.env["CES_BOOTSTRAP_SOCKET"]));
+  }
+
+  // CES managed-mode private data root — in managed deployments the CES
+  // data lives outside the Vellum root, so it isn't covered by the
+  // `protected/` entry above.
+  const cesDataDir = process.env["CES_DATA_DIR"];
+  if (cesDataDir) {
+    paths.push(cesDataDir);
+  } else if (process.env["CES_MANAGED_MODE"]) {
+    paths.push("/ces-data");
+  }
+
+  return paths;
+}
+
 const log = getLogger("shell-tool");
 
 class ShellTool implements Tool {
@@ -96,9 +146,33 @@ class ShellTool implements Tool {
       return { content: "Error: command contains null bytes", isError: true };
     }
 
+    const config = getConfig();
+    const shellLockdownActive =
+      isCesShellLockdownEnabled(config) &&
+      isUntrustedTrustClass(context.trustClass);
+
     const networkMode: "off" | "proxied" =
       input.network_mode === "proxied" ? "proxied" : "off";
 
+    // -----------------------------------------------------------------------
+    // CES shell lockdown — reject proxied credential sessions for untrusted
+    // actors when the lockdown flag is active. Proxied sessions grant the
+    // subprocess access to credentials through the egress proxy, which
+    // violates the secrecy guarantee.
+    // -----------------------------------------------------------------------
+    if (shellLockdownActive && networkMode === "proxied") {
+      log.warn(
+        { trustClass: context.trustClass },
+        "CES shell lockdown: rejecting proxied credential session for untrusted actor",
+      );
+      return {
+        content:
+          "Error: proxied credential sessions are not available in untrusted shell mode. " +
+          "Use the credential grant workflow to request access through a guardian.",
+        isError: true,
+      };
+    }
+
     const rawCredentialRefs: string[] = [];
     if (Array.isArray(input.credential_ids)) {
       for (const id of input.credential_ids) {
@@ -108,6 +182,24 @@ class ShellTool implements Tool {
       }
     }
 
+    // -----------------------------------------------------------------------
+    // CES shell lockdown — reject non-empty credential-ref mode for untrusted
+    // actors. Even when network_mode is "off", passing credential_ids could
+    // allow the model to probe stored credential metadata.
+    // -----------------------------------------------------------------------
+    if (shellLockdownActive && rawCredentialRefs.length > 0) {
+      log.warn(
+        { trustClass: context.trustClass, refCount: rawCredentialRefs.length },
+        "CES shell lockdown: rejecting credential-ref mode for untrusted actor",
+      );
+      return {
+        content:
+          "Error: credential references are not available in untrusted shell mode. " +
+          "Use the credential grant workflow to request access through a guardian.",
+        isError: true,
+      };
+    }
+
     // Resolve credential refs (UUID or service/field) to canonical UUIDs.
     // Fail fast if any ref is unresolvable — partial execution with missing
     // credentials is worse than a clear error.
@@ -152,7 +244,6 @@ class ShellTool implements Tool {
       credentialIds.push(...rawCredentialRefs);
     }
 
-    const config = getConfig();
     const { shellDefaultTimeoutSec, shellMaxTimeoutSec } = config.timeouts;
     const requestedSec =
       typeof input.timeout_seconds === "number"
@@ -213,13 +304,26 @@ class ShellTool implements Tool {
       Object.assign(env, proxyEnv);
     }
 
+    // Inject VELLUM_UNTRUSTED_SHELL=1 so assistant CLI commands can self-deny
+    // raw-token/secret reveal flows when invoked from an untrusted shell.
+    if (shellLockdownActive) {
+      env.VELLUM_UNTRUSTED_SHELL = "1";
+    }
+
     const result = await new Promise<ToolExecutionResult>((resolve) => {
       const stdoutChunks: Buffer[] = [];
       const stderrChunks: Buffer[] = [];
       let timedOut = false;
 
+      // CES shell lockdown: build deny-read paths for protected credential
+      // data, the protected dir, and data sub-dirs that contain secrets.
+      const denyReadPaths: string[] | undefined = shellLockdownActive
+        ? buildCesProtectedPaths()
+        : undefined;
+
       const wrapped = wrapCommand(command, context.workingDir, sandboxConfig, {
         networkMode,
+        denyReadPaths,
       });
       const child = spawn(wrapped.command, wrapped.args, {
         cwd: context.workingDir,

package/src/tools/tool-approval-handler.ts

@@ -198,7 +198,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -224,7 +223,6 @@ export class ToolApprovalHandler {
       log.warn(
         {
           toolName: name,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           trustClass: context.trustClass,
           reason: "guardian_only_policy",
@@ -238,7 +236,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -273,7 +270,8 @@ export class ToolApprovalHandler {
         toolName: name,
         inputDigest,
         consumingRequestId:
-          context.requestId ?? `preexec-${context.sessionId}-${Date.now()}`,
+          context.requestId ??
+          `preexec-${context.conversationId}-${Date.now()}`,
         executionChannel: context.executionChannel,
         conversationId: context.conversationId,
         callSessionId: context.callSessionId,
@@ -291,7 +289,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -320,7 +317,6 @@ export class ToolApprovalHandler {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -348,7 +344,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -382,7 +377,6 @@ export class ToolApprovalHandler {
             toolName: name,
             channelId: context.channelPermissionChannelId,
             category: tool.category,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             reason: "channel_permission_policy",
           },
@@ -395,7 +389,6 @@ export class ToolApprovalHandler {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -427,7 +420,6 @@ export class ToolApprovalHandler {
         log.info(
           {
             toolName: name,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             trustClass: context.trustClass,
             executionTarget,
@@ -451,7 +443,6 @@ export class ToolApprovalHandler {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -527,7 +518,6 @@ export class ToolApprovalHandler {
             log.info(
               {
                 toolName: name,
-                sessionId: context.sessionId,
                 conversationId: context.conversationId,
                 trustClass: context.trustClass,
                 executionTarget,
@@ -552,7 +542,6 @@ export class ToolApprovalHandler {
               executionTarget,
               input,
               workingDir: context.workingDir,
-              sessionId: context.sessionId,
               conversationId: context.conversationId,
               requestId: context.requestId,
               riskLevel,
@@ -592,7 +581,6 @@ export class ToolApprovalHandler {
           log.warn(
             {
               toolName: name,
-              sessionId: context.sessionId,
               conversationId: context.conversationId,
               trustClass: context.trustClass,
               executionTarget,
@@ -610,7 +598,6 @@ export class ToolApprovalHandler {
             executionTarget,
             input,
             workingDir: context.workingDir,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             requestId: context.requestId,
             riskLevel,
@@ -631,7 +618,6 @@ export class ToolApprovalHandler {
       log.warn(
         {
           toolName: name,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           trustClass: context.trustClass,
           executionTarget,
@@ -648,7 +634,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,

package/src/tools/tool-manifest.ts

@@ -6,8 +6,16 @@
  * so adding/removing tools only requires editing this manifest.
  */
 
+import { getConfig } from "../config/loader.js";
+import {
+  isCesSecureInstallEnabled,
+  isCesToolsEnabled,
+} from "../credential-execution/feature-gates.js";
 import { assetMaterializeTool } from "./assets/materialize.js";
 import { assetSearchTool } from "./assets/search.js";
+import { makeAuthenticatedRequestTool } from "./credential-execution/make-authenticated-request.js";
+import { manageSecureCommandTool } from "./credential-execution/manage-secure-command-tool.js";
+import { runAuthenticatedCommandTool } from "./credential-execution/run-authenticated-command.js";
 import { credentialStoreTool } from "./credentials/vault.js";
 import { fileEditTool } from "./filesystem/edit.js";
 import { fileReadTool } from "./filesystem/read.js";
@@ -84,3 +92,38 @@ export const explicitTools: Tool[] = [
   memoryRecallTool,
   credentialStoreTool,
 ];
+
+// ── CES tools (feature-flag gated) ──────────────────────────────────
+// Credential Execution Service tools are only registered when the
+// CES feature flag (`feature_flags.ces-tools.enabled`) is enabled.
+// This list is intentionally separate from `explicitTools` so that
+// initializeTools() in registry.ts can conditionally include them.
+
+/** All CES tools — stable references for the manifest snapshot. */
+export const cesTools: Tool[] = [
+  makeAuthenticatedRequestTool,
+  runAuthenticatedCommandTool,
+  manageSecureCommandTool,
+];
+
+/**
+ * Return CES tools only if the CES feature flag is enabled.
+ * Returns an empty array when the flag is disabled so callers can
+ * unconditionally iterate the result.
+ */
+export function getCesToolsIfEnabled(): Tool[] {
+  try {
+    const config = getConfig();
+    if (isCesToolsEnabled(config)) {
+      // manage_secure_command_tool is additionally gated behind the
+      // ces-secure-install flag so it can be rolled out independently.
+      const secureInstallEnabled = isCesSecureInstallEnabled(config);
+      return cesTools.filter(
+        (t) => t.name !== "manage_secure_command_tool" || secureInstallEnabled,
+      );
+    }
+  } catch {
+    // Config not yet loaded (e.g. during test setup) — CES tools stay off.
+  }
+  return [];
+}