@vellumai/assistant 0.4.55 → 0.4.57

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/parser.ts

@@ -38,7 +38,7 @@ export interface ParsedCommand {
 }
 
 const SHELL_PROGRAMS = new Set(["sh", "bash", "zsh", "dash", "ksh", "fish"]);
-// Script interpreters that can execute arbitrary code from stdin — piping
+// Script interpreters that can execute arbitrary code from stdin - piping
 // untrusted data into these is as dangerous as piping into a shell.
 const SCRIPT_INTERPRETERS = new Set([
   "python",
@@ -55,7 +55,7 @@ const STDIN_EXEC_FLAGS = new Set(["-c", "-e", "-"]);
 // Per-interpreter flags that consume the next argument as a value (not a filename).
 // Mapped by interpreter name since flags differ across interpreters
 // (e.g. -I is standalone in Python but takes a value in Ruby).
-// Note: `-m` is intentionally excluded — it means "run module", so the next arg
+// Note: `-m` is intentionally excluded - it means "run module", so the next arg
 // is a module name and the interpreter is NOT in stdin-exec mode.
 const INTERPRETER_VALUE_FLAGS: ReadonlyMap<
   string,
@@ -128,7 +128,7 @@ const initGuard = new PromiseGuard<void>();
  * In development / `bunx` the file lives under `node_modules/` relative
  * to the source tree.  In compiled Bun binaries `import.meta.dirname`
  * points into the virtual `/$bunfs/` filesystem where binary assets
- * don't exist — fall back to:
+ * don't exist - fall back to:
  *   1. `../Resources/<file>` (macOS .app bundle layout)
  *   2. Next to the compiled binary (process.execPath)
  * This matches the pattern used for compiled Bun binary asset resolution.
@@ -352,7 +352,7 @@ function extractSegments(node: TSNode): CommandSegment[] {
 }
 
 /**
- * Returns true when the interpreter args indicate stdin-exec mode — i.e. the
+ * Returns true when the interpreter args indicate stdin-exec mode - i.e. the
  * interpreter will read code from stdin (or from an inline -c/-e argument)
  * rather than from a file.  Concretely:
  *   - Any STDIN_EXEC_FLAGS present → stdin-exec
@@ -367,7 +367,7 @@ function isStdinExecMode(interpreter: string, args: string[]): boolean {
     if (STDIN_EXEC_FLAGS.has(arg)) return true;
     // First non-flag argument is a filename/module → file mode
     if (!arg.startsWith("-")) return false;
-    // Flags like -W, -X consume the next token as their value — skip it
+    // Flags like -W, -X consume the next token as their value - skip it
     if (valueFlags.has(arg)) i++;
   }
   // No positional arguments at all → interpreter reads from stdin
@@ -581,7 +581,7 @@ export async function parse(command: string): Promise<ParsedCommand> {
   const parser = await ensureParser();
   const tree = parser.parse(command);
   if (!tree) {
-    // Parser couldn't parse — treat as opaque
+    // Parser couldn't parse - treat as opaque
     return { segments: [], dangerousPatterns: [], hasOpaqueConstructs: true };
   }
   const rootNode = tree.rootNode;

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/sandbox-diagnostics.ts

@@ -46,7 +46,7 @@ function checkNativeBackend(): SandboxCheckResult {
       return {
         label: "Native sandbox (Linux bwrap)",
         ok: false,
-        detail: "bwrap not available — install bubblewrap",
+        detail: "bwrap not available - install bubblewrap",
       };
     }
   }

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 {
@@ -50,7 +100,7 @@ class ShellTool implements Tool {
             type: "string",
             description: "The shell command to execute",
           },
-          reason: {
+          activity: {
             type: "string",
             description:
               'Brief non-technical explanation of what this command does and why, shown to a non-technical user in the permission prompt. Avoid jargon and technical terms. Good: "to check if a required program is installed on your computer". Bad: "to check if gcloud CLI is installed". Good: "to download a helper program". Bad: "to run npm install".',
@@ -73,7 +123,7 @@ class ShellTool implements Tool {
               'Optional list of credential IDs to inject via the proxy when network_mode is "proxied".',
           },
         },
-        required: ["command", "reason"],
+        required: ["command", "activity"],
       },
     };
   }
@@ -90,15 +140,39 @@ class ShellTool implements Tool {
       };
     }
 
-    // Reject commands containing null bytes — they cause truncation at the
+    // Reject commands containing null bytes - they cause truncation at the
     // OS level while the parser sees the full string, enabling bypass.
     if (command.includes("\0")) {
       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,8 +182,26 @@ 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
+    // Fail fast if any ref is unresolvable - partial execution with missing
     // credentials is worse than a clear error.
     const credentialIds: string[] = [];
     if (networkMode === "proxied" && rawCredentialRefs.length > 0) {
@@ -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"
@@ -173,7 +264,7 @@ class ShellTool implements Tool {
       "Executing shell command",
     );
 
-    // Resolve sandbox config early — needed both for proxy env and command wrapping.
+    // Resolve sandbox config early - needed both for proxy env and command wrapping.
     const sandboxConfig =
       context.sandboxOverride != null
         ? { ...config.sandbox, enabled: context.sandboxOverride }
@@ -182,7 +273,7 @@ class ShellTool implements Tool {
     // Acquire proxy session if proxied mode is requested.
     // `getOrStartSession` serializes per-conversation so concurrent proxied
     // commands share a single session instead of each creating one.
-    // Sessions are NOT stopped here — the session manager's idle timer handles
+    // Sessions are NOT stopped here - the session manager's idle timer handles
     // cleanup after all commands finish (see resetIdleTimer / stopAllSessions).
     let proxyEnv: ProxyEnvVars | null = null;
 
@@ -200,7 +291,7 @@ class ShellTool implements Tool {
       } catch (err) {
         log.error({ err }, "Failed to start proxy session");
         return {
-          content: `Error: failed to start proxy session — ${
+          content: `Error: failed to start proxy session - ${
             err instanceof Error ? err.message : String(err)
           }`,
           isError: true,
@@ -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,
@@ -281,7 +385,7 @@ class ShellTool implements Tool {
         resolve({
           content: `Error spawning command: ${err.message}${
             (err as NodeJS.ErrnoException).code === "ENOENT"
-              ? ". The command was not found — check that it is installed and in PATH."
+              ? ". The command was not found - check that it is installed and in PATH."
               : ""
           }`,
           isError: true,

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

@@ -82,7 +82,7 @@ export async function waitForInlineGrant(
       return { outcome: "aborted" };
     }
 
-    // Check if the canonical request was rejected — exit early without
+    // Check if the canonical request was rejected - exit early without
     // waiting for the full timeout.
     const request = getCanonicalGuardianRequest(escalationRequestId);
     if (request && request.status === "denied") {
@@ -98,7 +98,7 @@ export async function waitForInlineGrant(
       return { outcome: "denied", requestId: escalationRequestId };
     }
 
-    // Try to consume the grant — if the guardian approved, the canonical
+    // Try to consume the grant - if the guardian approved, the canonical
     // decision primitive will have minted a scoped grant by now.
     const grantResult = await consumeGrantForInvocation(consumeParams, {
       maxWaitMs: 0,
@@ -112,7 +112,7 @@ export async function waitForInlineGrant(
           grantId: grantResult.grant.id,
           elapsedMs: maxWait - (deadline - Date.now()),
         },
-        "Grant found during inline wait — tool execution proceeding",
+        "Grant found during inline wait - tool execution proceeding",
       );
       return { outcome: "granted", grant: { id: grantResult.grant.id } };
     }
@@ -125,16 +125,25 @@ export async function waitForInlineGrant(
       toolName: consumeParams.toolName,
       maxWaitMs: maxWait,
     },
-    "Inline grant wait timed out — no guardian decision within budget",
+    "Inline grant wait timed out - no guardian decision within budget",
   );
   return { outcome: "timeout", requestId: escalationRequestId };
 }
 
+const UI_SURFACE_TOOLS = new Set(["ui_show", "ui_update", "ui_dismiss"]);
+
 function requiresGuardianApprovalForActor(
   toolName: string,
   input: Record<string, unknown>,
   executionTarget: ExecutionTarget,
 ): boolean {
+  // UI surface tools are passive, user-visible operations (cards, forms,
+  // tables). User input is voluntary and user-controlled — skip the guardian
+  // gate so they work during fresh onboarding before trust is established.
+  if (UI_SURFACE_TOOLS.has(toolName)) {
+    return false;
+  }
+
   // Side-effect tools always require guardian approval for untrusted actors.
   // Read-only host execution is also blocked because it can leak sensitive
   // local information (e.g. shell/file reads).
@@ -198,7 +207,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -224,7 +232,6 @@ export class ToolApprovalHandler {
       log.warn(
         {
           toolName: name,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           trustClass: context.trustClass,
           reason: "guardian_only_policy",
@@ -238,7 +245,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -273,7 +279,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 +298,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -320,7 +326,6 @@ export class ToolApprovalHandler {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -348,7 +353,6 @@ export class ToolApprovalHandler {
         executionTarget,
         input,
         workingDir: context.workingDir,
-        sessionId: context.sessionId,
         conversationId: context.conversationId,
         requestId: context.requestId,
         riskLevel,
@@ -382,7 +386,6 @@ export class ToolApprovalHandler {
             toolName: name,
             channelId: context.channelPermissionChannelId,
             category: tool.category,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             reason: "channel_permission_policy",
           },
@@ -395,7 +398,6 @@ export class ToolApprovalHandler {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -427,19 +429,18 @@ export class ToolApprovalHandler {
         log.info(
           {
             toolName: name,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             trustClass: context.trustClass,
             executionTarget,
             grantId: grantResult.grant.id,
           },
-          "Scoped grant consumed — allowing untrusted actor tool invocation",
+          "Scoped grant consumed - allowing untrusted actor tool invocation",
         );
 
         return { allowed: true, tool, grantConsumed: true };
       }
 
-      // Treat abort as a cancellation — not a grant denial. This matches
+      // Treat abort as a cancellation - not a grant denial. This matches
       // the abort check at the top of checkPreExecutionGates so the caller
       // sees a consistent "Cancelled" result instead of a spurious
       // guardian_approval_required denial during voice barge-in.
@@ -451,7 +452,6 @@ export class ToolApprovalHandler {
           executionTarget,
           input,
           workingDir: context.workingDir,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           requestId: context.requestId,
           riskLevel,
@@ -467,12 +467,12 @@ export class ToolApprovalHandler {
         };
       }
 
-      // No matching grant or race condition — deny or wait inline.
+      // No matching grant or race condition - deny or wait inline.
       //
       // For verified non-guardian actors (trusted_contact) with sufficient
       // context, escalate to the guardian by creating a canonical
       // tool_grant_request. Then wait bounded for the grant to become
-      // available — this lets the tool call succeed inline after guardian
+      // available - this lets the tool call succeed inline after guardian
       // approval without the requester having to retry manually.
       //
       // Unverified actors remain fail-closed with no escalation or wait.
@@ -527,14 +527,13 @@ export class ToolApprovalHandler {
             log.info(
               {
                 toolName: name,
-                sessionId: context.sessionId,
                 conversationId: context.conversationId,
                 trustClass: context.trustClass,
                 executionTarget,
                 grantId: waitResult.grant.id,
                 escalationRequestId: escalation.requestId,
               },
-              "Inline grant wait succeeded — allowing trusted contact tool invocation",
+              "Inline grant wait succeeded - allowing trusted contact tool invocation",
             );
             return { allowed: true, tool, grantConsumed: true };
           }
@@ -552,7 +551,6 @@ export class ToolApprovalHandler {
               executionTarget,
               input,
               workingDir: context.workingDir,
-              sessionId: context.sessionId,
               conversationId: context.conversationId,
               requestId: context.requestId,
               riskLevel,
@@ -592,7 +590,6 @@ export class ToolApprovalHandler {
           log.warn(
             {
               toolName: name,
-              sessionId: context.sessionId,
               conversationId: context.conversationId,
               trustClass: context.trustClass,
               executionTarget,
@@ -601,7 +598,7 @@ export class ToolApprovalHandler {
               waitOutcome: waitResult.outcome,
               escalationRequestId: escalation.requestId,
             },
-            "Inline grant wait ended without approval — denying trusted contact tool invocation",
+            "Inline grant wait ended without approval - denying trusted contact tool invocation",
           );
           const durationMs = Date.now() - startTime;
           emitLifecycleEvent({
@@ -610,7 +607,6 @@ export class ToolApprovalHandler {
             executionTarget,
             input,
             workingDir: context.workingDir,
-            sessionId: context.sessionId,
             conversationId: context.conversationId,
             requestId: context.requestId,
             riskLevel,
@@ -623,15 +619,14 @@ export class ToolApprovalHandler {
             result: { content: escalationMessage, isError: true },
           };
         }
-        // escalation.failed — fall through to generic denial.
+        // escalation.failed - fall through to generic denial.
       }
 
-      // Unknown/unverified actors or escalation failures — generic denial.
+      // Unknown/unverified actors or escalation failures - generic denial.
       const reason = guardianApprovalDeniedMessage(context.trustClass, name);
       log.warn(
         {
           toolName: name,
-          sessionId: context.sessionId,
           conversationId: context.conversationId,
           trustClass: context.trustClass,
           executionTarget,
@@ -648,7 +643,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

@@ -1,13 +1,21 @@
 /**
- * Declarative tool manifest — single place to inspect what gets registered.
+ * Declarative tool manifest - single place to inspect what gets registered.
  *
  * Each entry describes HOW a tool (or group of tools) gets loaded and
  * registered.  `initializeTools()` in `registry.ts` iterates this list
  * 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";
@@ -65,7 +73,7 @@ export const eagerModuleToolNames: string[] = [
 // a test registry reset) and tools that have always been explicit.
 
 export const explicitTools: Tool[] = [
-  // Previously-eager tools — kept here so initializeTools() can re-register
+  // Previously-eager tools - kept here so initializeTools() can re-register
   // them after __resetRegistryForTesting() clears the registry (ESM caching
   // prevents their side-effect registrations from re-running).
   shellTool,
@@ -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 [];
+}