@vellumai/assistant 0.3.0

package/src/tools/tasks/work-item-list.ts

@@ -0,0 +1,55 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { listWorkItems, type WorkItem, type WorkItemStatus } from '../../work-items/work-item-store.js';
+
+const PRIORITY_LABELS: Record<number, string> = { 0: 'High', 1: 'Medium', 2: 'Low' };
+
+function formatTaskList(items: WorkItem[]): string {
+  const lines: string[] = [];
+  for (const item of items) {
+    const priority = PRIORITY_LABELS[item.priorityTier] ?? 'Medium';
+    const status = item.status.replace(/_/g, ' ');
+    lines.push(`- [${priority}] ${item.title} (${status})`);
+  }
+  return lines.join('\n');
+}
+
+export async function executeTaskListShow(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  try {
+    const statusFilter = input.status as string | string[] | undefined;
+
+    let items;
+    if (typeof statusFilter === 'string') {
+      items = listWorkItems({ status: statusFilter as WorkItemStatus });
+    } else if (Array.isArray(statusFilter)) {
+      // listWorkItems only supports a single status filter, so we fetch all
+      // and filter client-side when an array is provided
+      const allItems = listWorkItems();
+      const allowed = new Set(statusFilter);
+      items = allItems.filter((item) => allowed.has(item.status));
+    } else {
+      items = listWorkItems();
+    }
+
+    const count = items.length;
+    const filtered = statusFilter !== undefined;
+
+    if (count === 0) {
+      const suffix = filtered ? 'no items matching filter.' : 'no tasks queued.';
+      return { content: `Opened Tasks window \u2014 ${suffix}`, isError: false };
+    }
+
+    const label = filtered
+      ? `${count} ${Array.isArray(statusFilter) ? 'matching' : statusFilter} item${count === 1 ? '' : 's'}`
+      : `${count} item${count === 1 ? '' : 's'}`;
+
+    const taskList = formatTaskList(items);
+
+    return { content: `Opened Tasks window (${label}).\n\nCurrent tasks:\n${taskList}`, isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}

package/src/tools/tasks/work-item-remove.ts

@@ -0,0 +1,60 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { resolveWorkItem, removeWorkItemFromQueue, identifyEntityById, buildTaskTemplateMismatchError, type WorkItemStatus } from '../../work-items/work-item-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('task-list-remove');
+
+export async function executeTaskListRemove(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const selectorType = input.work_item_id ? 'work_item_id' : input.task_id ? 'task_id' : input.task_name ? 'task_name' : input.title ? 'title' : 'none';
+
+  try {
+    const selector = {
+      workItemId: input.work_item_id as string | undefined,
+      taskId: input.task_id as string | undefined,
+      title: (input.task_name ?? input.title) as string | undefined,
+      priorityTier: input.priority_tier as number | undefined,
+      status: input.status as WorkItemStatus | undefined,
+      createdOrder: input.created_order as number | undefined,
+    };
+
+    const resolveResult = resolveWorkItem(selector);
+
+    if (resolveResult.status === 'not_found') {
+      // When the model passes an ID directly, check if it's a task template
+      if (selector.workItemId) {
+        const entity = identifyEntityById(selector.workItemId);
+        if (entity.type === 'task_template') {
+          log.warn({ selectorType, inputId: selector.workItemId }, 'task template ID passed as work_item_id');
+          return {
+            content: `Error: ${buildTaskTemplateMismatchError(selector.workItemId, entity.title!, 'task_delete to delete task templates')}`,
+            isError: true,
+          };
+        }
+      }
+      log.warn({ selectorType, error: resolveResult.message }, 'work item not found for removal');
+      return { content: `Error: ${resolveResult.message}`, isError: true };
+    }
+
+    if (resolveResult.status === 'ambiguous') {
+      log.warn({ selectorType, matchCount: resolveResult.matches.length }, 'ambiguous selector for removal');
+      return { content: `Error: ${resolveResult.message}`, isError: true };
+    }
+
+    const item = resolveResult.workItem;
+
+    log.info({ selectorType, selectorValue: input[selectorType], resolvedWorkItemId: item.id, title: item.title }, 'resolved work item for removal');
+
+    const removeResult = removeWorkItemFromQueue(item.id);
+
+    log.info({ resolvedWorkItemId: item.id, deletedCount: 1 }, 'work item removed');
+
+    return { content: removeResult.message, isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ selectorType, error: msg }, 'remove failed');
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}

package/src/tools/tasks/work-item-run.ts

@@ -0,0 +1,78 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { getWorkItem, listWorkItems, identifyEntityById } from '../../work-items/work-item-store.js';
+import { runWorkItemInBackground } from '../../work-items/work-item-runner.js';
+import { getTask } from '../../tasks/task-store.js';
+
+export async function executeTaskQueueRun(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const workItemId = input.work_item_id as string | undefined;
+  const taskName = input.task_name as string | undefined;
+  const title = input.title as string | undefined;
+
+  if (!workItemId && !taskName && !title) {
+    return {
+      content: 'Error: Provide work_item_id, task_name, or title to identify the task to run.',
+      isError: true,
+    };
+  }
+
+  try {
+    let resolvedId: string | undefined;
+
+    if (workItemId) {
+      const item = getWorkItem(workItemId);
+      if (!item) {
+        const entity = identifyEntityById(workItemId);
+        if (entity.type === 'task_template') {
+          return {
+            content: `Error: "${workItemId}" is a task template ID, not a work item. Use task_list_show to find the work item ID.`,
+            isError: true,
+          };
+        }
+        return { content: `Error: No work item found with ID "${workItemId}".`, isError: true };
+      }
+      resolvedId = item.id;
+    } else {
+      // Search by task_name or title among active work items
+      const needle = (taskName ?? title)!.toLowerCase();
+      const allItems = listWorkItems();
+      const activeItems = allItems.filter((i) => !['archived', 'done'].includes(i.status));
+      const matches = activeItems.filter((i) => i.title.toLowerCase().includes(needle));
+
+      if (matches.length === 0) {
+        return {
+          content: `Error: No active work item matching "${taskName ?? title}". Use task_list_show to see your task queue.`,
+          isError: true,
+        };
+      }
+
+      if (matches.length > 1) {
+        const lines = [`Multiple work items match "${taskName ?? title}". Please specify by ID:`, ''];
+        for (const m of matches) {
+          lines.push(`- ${m.title} (ID: ${m.id}, status: ${m.status})`);
+        }
+        return { content: lines.join('\n'), isError: true };
+      }
+
+      resolvedId = matches[0].id;
+    }
+
+    const result = runWorkItemInBackground(resolvedId);
+
+    if (!result.success) {
+      return { content: `Error: ${result.error}`, isError: true };
+    }
+
+    const item = getWorkItem(resolvedId)!;
+    const task = getTask(item.taskId);
+    return {
+      content: `Started running task "${item.title}"${task ? ` (template: ${task.title})` : ''}. It will execute in the background. Use task_list_show to check progress.`,
+      isError: false,
+    };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}

package/src/tools/tasks/work-item-update.ts

@@ -0,0 +1,114 @@
+import type { ToolContext, ToolExecutionResult } from '../types.js';
+import { resolveWorkItem, updateWorkItem, identifyEntityById, buildTaskTemplateMismatchError, type WorkItemStatus } from '../../work-items/work-item-store.js';
+import { getLogger } from '../../util/logger.js';
+
+const log = getLogger('task-list-update');
+
+const PRIORITY_LABELS: Record<number, string> = {
+  0: 'high',
+  1: 'medium',
+  2: 'low',
+};
+
+export async function executeTaskListUpdate(
+  input: Record<string, unknown>,
+  _context: ToolContext,
+): Promise<ToolExecutionResult> {
+  const selectorType = input.work_item_id ? 'work_item_id' : input.task_id ? 'task_id' : input.task_name ? 'task_name' : input.title ? 'title' : 'none';
+
+  try {
+    // Build selector from whichever identifier was provided
+    const selector = {
+      workItemId: input.work_item_id as string | undefined,
+      taskId: input.task_id as string | undefined,
+      title: (input.task_name ?? input.title) as string | undefined,
+      priorityTier: input.filter_priority_tier as number | undefined,
+      status: input.filter_status as WorkItemStatus | undefined,
+      createdOrder: input.created_order as number | undefined,
+    };
+
+    // Resolve the target work item
+    const result = resolveWorkItem(selector);
+
+    if (result.status === 'not_found') {
+      // When the model passes an ID directly, check if it's a task template
+      if (selector.workItemId) {
+        const entity = identifyEntityById(selector.workItemId);
+        if (entity.type === 'task_template') {
+          log.warn({ selectorType, inputId: selector.workItemId }, 'task template ID passed as work_item_id');
+          return {
+            content: `Error: ${buildTaskTemplateMismatchError(selector.workItemId, entity.title!, 'task_delete to remove task templates, or task_list to view them')}`,
+            isError: true,
+          };
+        }
+      }
+      log.warn({ selectorType, error: result.message }, 'work item not found for update');
+      return { content: `Error: ${result.message}`, isError: true };
+    }
+
+    if (result.status === 'ambiguous') {
+      log.warn({ selectorType, matchCount: result.matches.length }, 'ambiguous selector for update');
+      return { content: `Error: ${result.message}`, isError: true };
+    }
+
+    const item = result.workItem;
+
+    // Block direct transitions to 'done' — the only path to done is
+    // through the Review action (handleWorkItemComplete in the daemon).
+    if (input.status === 'done') {
+      log.warn({ selectorType, resolvedWorkItemId: item.id }, 'rejected attempt to set status to done directly');
+      return {
+        content: 'Error: Cannot set status to \'done\' directly. Use the Review action in the Tasks window.',
+        isError: true,
+      };
+    }
+
+    log.info({ selectorType, selectorValue: input[selectorType], resolvedWorkItemId: item.id }, 'resolved work item for update');
+
+    // Build updates from provided fields
+    const updates: Partial<{
+      priorityTier: number;
+      notes: string;
+      status: WorkItemStatus;
+      sortIndex: number;
+    }> = {};
+    if (input.priority_tier !== undefined) updates.priorityTier = input.priority_tier as number;
+    if (input.notes !== undefined) updates.notes = input.notes as string;
+    if (input.status !== undefined) updates.status = input.status as WorkItemStatus;
+    if (input.sort_index !== undefined) updates.sortIndex = input.sort_index as number;
+
+    if (Object.keys(updates).length === 0) {
+      log.warn({ selectorType, resolvedWorkItemId: item.id }, 'update called with no fields to update');
+      return {
+        content: 'No updates specified. Provide at least one field to update (priority_tier, notes, status, sort_index).',
+        isError: true,
+      };
+    }
+
+    const updated = updateWorkItem(item.id, updates);
+    if (!updated) {
+      log.error({ selectorType, resolvedWorkItemId: item.id, updates }, 'updateWorkItem returned null');
+      return {
+        content: `Error: Failed to update work item "${item.title}".`,
+        isError: true,
+      };
+    }
+
+    log.info({ resolvedWorkItemId: item.id, updatedFields: Object.keys(updates) }, 'work item updated');
+
+    // Build confirmation message
+    const parts: string[] = [`Updated "${updated.title}"`];
+    if (input.priority_tier !== undefined) {
+      parts.push(`priority → ${PRIORITY_LABELS[updated.priorityTier] ?? updated.priorityTier}`);
+    }
+    if (input.notes !== undefined) parts.push('notes updated');
+    if (input.status !== undefined) parts.push(`status → ${updated.status}`);
+    if (input.sort_index !== undefined) parts.push(`sort index → ${updated.sortIndex}`);
+
+    return { content: parts.join(', ') + '.', isError: false };
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    log.error({ selectorType, error: msg }, 'update failed');
+    return { content: `Error: ${msg}`, isError: true };
+  }
+}

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

@@ -0,0 +1,372 @@
+import { execFileSync } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, resolve, relative, posix } from 'node:path';
+import { ToolError } from '../../../util/errors.js';
+import { getLogger } from '../../../util/logger.js';
+import type { DockerConfig } from '../../../config/types.js';
+import type { SandboxBackend, SandboxResult, WrapOptions } from './types.js';
+
+const log = getLogger('docker-sandbox');
+
+export const DEFAULT_SANDBOX_IMAGE = 'vellum-sandbox:latest';
+
+/**
+ * Fallback defaults when DockerBackend is constructed without explicit config.
+ * Must stay in sync with DockerConfigSchema defaults in config/schema.ts.
+ */
+const DEFAULTS: Required<DockerConfig> = {
+  image: DEFAULT_SANDBOX_IMAGE,
+  shell: 'bash',
+  cpus: 1,
+  memoryMb: 512,
+  pidsLimit: 256,
+  network: 'none',
+};
+
+/**
+ * Characters that are dangerous in Docker mount arguments or shell commands.
+ * Commas are included because Docker's --mount flag uses them as field
+ * delimiters — a path containing a comma could inject extra key=value pairs
+ * (e.g. overriding dst= or src=) into the mount specification.
+ */
+const UNSAFE_PATH_CHARS = /[\x00\n\r,]/;
+
+/**
+ * Cache positive preflight results only, matching the bwrap pattern in native.ts.
+ * Negative results are not cached so that installing/starting Docker after the
+ * daemon starts takes effect without a restart.
+ */
+let dockerCliAvailable = false;
+let dockerDaemonReachable = false;
+const imageAvailableCache = new Set<string>();
+const mountProbeCache = new Set<string>();
+/** Maps image → resolved shell path (e.g. 'bash' → 'bash', or fell back to 'sh'). */
+const shellResolvedCache = new Map<string, string>();
+
+/** Exported for tests to reset cached state between runs. */
+export function _resetDockerChecks(): void {
+  dockerCliAvailable = false;
+  dockerDaemonReachable = false;
+  imageAvailableCache.clear();
+  mountProbeCache.clear();
+  shellResolvedCache.clear();
+}
+
+function checkDockerCli(): void {
+  if (dockerCliAvailable) return;
+  try {
+    execFileSync('docker', ['--version'], { stdio: 'ignore', timeout: 5000 });
+    dockerCliAvailable = true;
+  } catch {
+    throw new ToolError(
+      'Docker CLI is not installed or not in PATH. Install Docker: https://docs.docker.com/get-docker/',
+      'bash',
+    );
+  }
+}
+
+function checkDockerDaemon(): void {
+  if (dockerDaemonReachable) return;
+  try {
+    execFileSync('docker', ['info'], { stdio: 'ignore', timeout: 10000 });
+    dockerDaemonReachable = true;
+  } catch {
+    throw new ToolError(
+      'Docker daemon is not running. Start Docker Desktop or run "sudo systemctl start docker".',
+      'bash',
+    );
+  }
+}
+
+/**
+ * Resolve the path to Dockerfile.sandbox relative to this source file.
+ * Works in both development (source layout) and bundled environments.
+ *
+ * In compiled Bun binaries, import.meta.dirname resolves into the virtual
+ * $bunfs filesystem, so the Dockerfile won't exist there. Fall back to
+ * looking next to the compiled binary (process.execPath) in that case.
+ */
+function getSandboxDockerfilePath(): string {
+  const dir = import.meta.dirname ?? __dirname;
+  const sourcePath = resolve(dir, '../../../../Dockerfile.sandbox');
+
+  // In compiled Bun binaries, dir points into /$bunfs/ which is virtual.
+  // Fall back to looking next to the compiled binary itself.
+  if (!existsSync(sourcePath) && dir.startsWith('/$bunfs/')) {
+    return resolve(dirname(process.execPath), 'Dockerfile.sandbox');
+  }
+
+  return sourcePath;
+}
+
+function checkImageAvailable(image: string): void {
+  if (imageAvailableCache.has(image)) return;
+  try {
+    // Use execFileSync to avoid shell interpolation of the image name.
+    execFileSync('docker', ['image', 'inspect', image], { stdio: 'ignore', timeout: 10000 });
+    imageAvailableCache.add(image);
+    return;
+  } catch {
+    // Image not available locally — try to build or pull it.
+  }
+
+  // For the default sandbox image, build from Dockerfile.sandbox instead of pulling.
+  if (image === DEFAULT_SANDBOX_IMAGE) {
+    const dockerfile = getSandboxDockerfilePath();
+    if (existsSync(dockerfile)) {
+      log.info(`Building sandbox image "${image}" from ${dockerfile}...`);
+      try {
+        // --no-cache avoids stale apt-get layers with expired GPG signatures.
+        execFileSync('docker', ['build', '--no-cache', '-t', image, '-f', dockerfile, '.'], {
+          stdio: ['ignore', 'ignore', 'pipe'],
+          timeout: 120000,
+          cwd: resolve(dockerfile, '..'),
+        });
+        imageAvailableCache.add(image);
+        return;
+      } catch (err: unknown) {
+        const stderr = err instanceof Error && 'stderr' in err
+          ? String((err as { stderr: unknown }).stderr).trim()
+          : '';
+        const detail = stderr ? `\n\nBuild output:\n${stderr}` : '';
+        throw new ToolError(
+          `Failed to build sandbox image "${image}" from ${dockerfile}. ` +
+          'Check Docker is running and try building manually: ' +
+          `docker build --no-cache -t ${image} -f ${dockerfile} ${resolve(dockerfile, '..')}` +
+          detail,
+          'bash',
+        );
+      }
+    }
+
+    // Dockerfile not found — can't build the local-only image and pulling won't work.
+    throw new ToolError(
+      `Cannot find Dockerfile.sandbox to build "${image}". ` +
+      'This image is built locally and is not available from a registry. ' +
+      'If you have the Vellum source tree, build it manually:\n' +
+      '  docker build --no-cache -t vellum-sandbox:latest -f assistant/Dockerfile.sandbox assistant\n' +
+      'Or set sandbox.docker.image to a different image in your config.',
+      'bash',
+    );
+  }
+
+  log.info(`Docker image "${image}" not found locally, pulling...`);
+  try {
+    execFileSync('docker', ['pull', image], { stdio: 'ignore', timeout: 120000 });
+    imageAvailableCache.add(image);
+  } catch {
+    throw new ToolError(
+      `Failed to pull Docker image "${image}". Check your network connection or pull it manually: docker pull ${image}`,
+      'bash',
+    );
+  }
+}
+
+function checkMountProbe(sandboxRoot: string, image: string): void {
+  const cacheKey = `${sandboxRoot}\0${image}`;
+  if (mountProbeCache.has(cacheKey)) return;
+  try {
+    execFileSync(
+      'docker',
+      [
+        'run', '--rm',
+        '--mount', `type=bind,src=${sandboxRoot},dst=/workspace`,
+        image, 'test', '-w', '/workspace',
+      ],
+      { stdio: 'ignore', timeout: 15000 },
+    );
+    mountProbeCache.add(cacheKey);
+  } catch {
+    throw new ToolError(
+      'Cannot bind-mount the sandbox root into a Docker container or /workspace is not writable. ' +
+      'If using Docker Desktop, enable file sharing for this path in Settings > Resources > File Sharing.',
+      'bash',
+    );
+  }
+}
+
+/**
+ * Verify the configured shell exists in the image.  If the requested shell
+ * (e.g. 'bash') is missing, fall back to 'sh' which is available on virtually
+ * every Linux image.  If neither exists the image is too minimal to use.
+ */
+function resolveShell(image: string, shell: string): string {
+  const cacheKey = `${image}\0${shell}`;
+  const cached = shellResolvedCache.get(cacheKey);
+  if (cached) return cached;
+
+  // Try the configured shell first.
+  try {
+    execFileSync('docker', ['run', '--rm', image, shell, '-c', 'true'], {
+      stdio: 'ignore',
+      timeout: 15000,
+    });
+    shellResolvedCache.set(cacheKey, shell);
+    return shell;
+  } catch {
+    // configured shell not available — try sh fallback
+  }
+
+  if (shell === 'sh') {
+    throw new ToolError(
+      `Shell "sh" is not available in Docker image "${image}". The image may be too minimal for sandbox use.`,
+      'bash',
+    );
+  }
+
+  try {
+    execFileSync('docker', ['run', '--rm', image, 'sh', '-c', 'true'], {
+      stdio: 'ignore',
+      timeout: 15000,
+    });
+    log.warn(`Shell "${shell}" not found in image "${image}", falling back to "sh"`);
+    shellResolvedCache.set(cacheKey, 'sh');
+    return 'sh';
+  } catch {
+    throw new ToolError(
+      `Neither "${shell}" nor "sh" is available in Docker image "${image}". ` +
+      'Choose a different image or set sandbox.docker.shell to a shell that exists in the image.',
+      'bash',
+    );
+  }
+}
+
+/**
+ * Validate that a path is safe to use in Docker mount arguments.
+ * Rejects paths containing null bytes, newlines, or carriage returns which
+ * could cause argument injection or parsing issues.
+ */
+function validatePathSafety(path: string, label: string): void {
+  if (UNSAFE_PATH_CHARS.test(path)) {
+    throw new ToolError(
+      `${label} contains characters that are unsafe for Docker mount arguments. ` +
+      'Refusing to execute. Remove null bytes, newlines, carriage returns, or commas from the path.',
+      'bash',
+    );
+  }
+}
+
+/**
+ * Docker sandbox backend that wraps commands in ephemeral containers.
+ *
+ * Each invocation produces a single `docker run --rm` command — no long-lived
+ * container state. The sandbox filesystem root is bind-mounted to /workspace
+ * and the host UID:GID is forwarded to prevent permission drift.
+ *
+ * On first use, runs preflight checks (CLI, daemon, image, mount probe) and
+ * fails closed with actionable error messages if any check fails.
+ */
+export class DockerBackend implements SandboxBackend {
+  private readonly sandboxRoot: string;
+  private readonly config: Required<DockerConfig>;
+  private readonly uid: number;
+  private readonly gid: number;
+
+  constructor(
+    sandboxRoot: string,
+    config?: Partial<Required<DockerConfig>>,
+    uid?: number,
+    gid?: number,
+  ) {
+    // Resolve to an absolute path first, then follow symlinks.
+    // This prevents path traversal via ../.. or symlink tricks.
+    const resolved = resolve(sandboxRoot);
+    this.sandboxRoot = realpathSync(resolved);
+    validatePathSafety(this.sandboxRoot, 'Sandbox root');
+    this.config = { ...DEFAULTS, ...config };
+    if (uid != null) {
+      this.uid = uid;
+    } else if (process.getuid) {
+      this.uid = process.getuid();
+    } else {
+      throw new ToolError(
+        'Docker sandbox requires POSIX UID/GID APIs (process.getuid/getgid) which are not available on this platform.',
+        'bash',
+      );
+    }
+    this.gid = gid ?? (process.getgid ? process.getgid() : this.uid);
+  }
+
+  /**
+   * Run preflight checks in dependency order. Each check is cached
+   * on success; failures re-check on every call.  Returns the resolved
+   * shell (may differ from config if the configured shell is missing).
+   */
+  preflight(): string {
+    checkDockerCli();
+    checkDockerDaemon();
+    checkImageAvailable(this.config.image);
+    checkMountProbe(this.sandboxRoot, this.config.image);
+    return resolveShell(this.config.image, this.config.shell);
+  }
+
+  wrap(command: string, workingDir: string, options?: WrapOptions): SandboxResult {
+    // Preflight: fail closed if Docker is not usable.
+    const shell = this.preflight();
+
+    // Resolve + follow symlinks for the working directory.
+    const resolved = resolve(workingDir);
+    const realWorkDir = realpathSync(resolved);
+    const realRoot = this.sandboxRoot;
+
+    // Validate path safety for mount/workdir args.
+    validatePathSafety(realWorkDir, 'Working directory');
+
+    // Fail closed: working dir must be inside sandbox root.
+    if (!realWorkDir.startsWith(realRoot + '/') && realWorkDir !== realRoot) {
+      log.error(
+        'Working directory is outside sandbox root — refusing to execute',
+      );
+      throw new ToolError(
+        'Working directory is outside the sandbox root. Refusing to execute.',
+        'bash',
+      );
+    }
+
+    // Map host working dir to container path under /workspace.
+    const relPath = relative(realRoot, realWorkDir);
+    const containerWorkDir =
+      relPath === '' ? '/workspace' : posix.join('/workspace', relPath);
+
+    const { image, cpus, memoryMb, pidsLimit, network } = this.config;
+
+    // Per-invocation network override: proxied mode needs bridge networking
+    // so the container can reach the proxy on the host. Default ('off' or
+    // undefined) preserves the config-level network setting.
+    const effectiveNetwork =
+      options?.networkMode === 'proxied' ? 'bridge' : network;
+
+    // Every flag is a separate argv segment — no shell interpolation occurs.
+    const args: string[] = [
+      'run',
+      '--rm',
+      `--network=${effectiveNetwork}`,
+      // When proxied, map host.docker.internal to the host machine so the
+      // container can reach the proxy daemon listening on the host loopback.
+      ...(options?.networkMode === 'proxied'
+        ? ['--add-host=host.docker.internal:host-gateway']
+        : []),
+      `--cpus=${cpus}`,
+      `--memory=${memoryMb}m`,
+      `--pids-limit=${pidsLimit}`,
+      '--cap-drop=ALL',
+      '--security-opt=no-new-privileges',
+      // Read-only container root prevents writes outside explicit mounts.
+      '--read-only',
+      // Writable tmpfs for /tmp — required for shell behavior, temp files, etc.
+      '--tmpfs', '/tmp:rw,nosuid,nodev,noexec',
+      '--mount',
+      `type=bind,src=${realRoot},dst=/workspace`,
+      '--workdir',
+      containerWorkDir,
+      '--user',
+      `${this.uid}:${this.gid}`,
+      image,
+      shell,
+      '-c',
+      command,
+    ];
+
+    return { command: 'docker', args, sandboxed: true };
+  }
+}