mulmoclaude 0.1.0

package/server/agent/config.ts

@@ -0,0 +1,414 @@
+import { join } from "path";
+import { homedir, tmpdir } from "os";
+import type { Role } from "../../src/config/roles.js";
+import { mcpTools, isMcpToolEnabled } from "./mcp-tools/index.js";
+import { MCP_PLUGIN_NAMES } from "./plugin-names.js";
+import type { McpServerSpec } from "../system/config.js";
+import { getCurrentToken } from "../api/auth/token.js";
+import type { Attachment } from "@mulmobridge/protocol";
+import { isImageMime, isNativeAttachmentMime } from "@mulmobridge/client";
+import { convertAttachment } from "./attachmentConverter.js";
+import { log } from "../system/logger/index.js";
+
+export const CONTAINER_WORKSPACE_PATH = "/home/node/mulmoclaude";
+
+const BASE_ALLOWED_TOOLS = ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"];
+
+const MCP_PLUGINS = new Set([...MCP_PLUGIN_NAMES, ...mcpTools.filter(isMcpToolEnabled).map((t) => t.definition.name)]);
+
+export function getActivePlugins(role: Role): string[] {
+  return role.availablePlugins.filter((p) => MCP_PLUGINS.has(p));
+}
+
+export interface McpConfigParams {
+  /** Stable chat session ID (not the per-run UUID). Used as SESSION_ID
+   *  env var so the MCP server's /internal/* callbacks address the
+   *  session store by chatSessionId. */
+  chatSessionId: string;
+  port: number;
+  activePlugins: string[];
+  roleIds: string[];
+  useDocker?: boolean;
+  // User-defined MCP servers from <workspace>/config/mcp.json.
+  // Keys become the server id in the generated --mcp-config file;
+  // values are the standard Claude CLI server spec (HTTP or stdio).
+  userServers?: Record<string, McpServerSpec>;
+}
+
+// In Docker mode the sandbox container can't reach the host's
+// `localhost` / `127.0.0.1` — those refer to the container's own
+// loopback interface. Rewriting to `host.docker.internal` keeps
+// user-configured local MCP servers reachable.
+export function rewriteLocalhostForDocker(url: string, useDocker: boolean): string {
+  if (!useDocker) return url;
+  return url.replace(/^(https?:\/\/)(localhost|127\.0\.0\.1)(?=[:/]|$)/, "$1host.docker.internal");
+}
+
+function prepareUserHttpServer(spec: Extract<McpServerSpec, { type: "http" }>, useDocker: boolean): McpServerSpec {
+  return {
+    ...spec,
+    url: rewriteLocalhostForDocker(spec.url, useDocker),
+  };
+}
+
+// Rewrite stdio args so paths that point inside the host workspace are
+// translated to their container equivalents. Paths outside the
+// workspace are left alone — the caller surfaces a warning in the UI
+// before they get this far.
+function prepareUserStdioServer(spec: Extract<McpServerSpec, { type: "stdio" }>, useDocker: boolean, hostWorkspacePath: string): McpServerSpec {
+  if (!useDocker) return spec;
+  const normalisedWs = hostWorkspacePath.endsWith("/") ? hostWorkspacePath : `${hostWorkspacePath}/`;
+  const args = spec.args?.map((arg) => {
+    if (arg === hostWorkspacePath) return CONTAINER_WORKSPACE_PATH;
+    if (arg.startsWith(normalisedWs)) {
+      const rel = arg.slice(normalisedWs.length);
+      return `${CONTAINER_WORKSPACE_PATH}/${rel}`;
+    }
+    return arg;
+  });
+  return { ...spec, args };
+}
+
+export function prepareUserServers(userServers: Record<string, McpServerSpec>, useDocker: boolean, hostWorkspacePath: string): Record<string, McpServerSpec> {
+  const out: Record<string, McpServerSpec> = {};
+  for (const [id, spec] of Object.entries(userServers)) {
+    if (spec.enabled === false) continue;
+    if (spec.type === "http") {
+      out[id] = prepareUserHttpServer(spec, useDocker);
+    } else {
+      out[id] = prepareUserStdioServer(spec, useDocker, hostWorkspacePath);
+    }
+  }
+  return out;
+}
+
+// When running in Docker the MCP server subprocess won't inherit the host
+// environment. Pass sentinel values for required env vars of enabled tools
+// so isMcpToolEnabled() returns the same result inside the container.
+// The actual API calls happen on the host server, so real values aren't needed.
+function collectMcpToolSentinelEnv(): Record<string, string> {
+  const env: Record<string, string> = {};
+  for (const tool of mcpTools.filter(isMcpToolEnabled)) {
+    for (const key of tool.requiredEnv ?? []) {
+      if (process.env[key]) env[key] = "1";
+    }
+  }
+  return env;
+}
+
+function buildMulmoclaudeServer(params: { chatSessionId: string; port: number; activePlugins: string[]; roleIds: string[]; useDocker: boolean }): object {
+  const { chatSessionId, port, activePlugins, roleIds, useDocker } = params;
+  const projectRoot = process.cwd();
+  const command = useDocker ? "tsx" : join(projectRoot, "node_modules/.bin/tsx");
+  const mcpServerPath = useDocker ? "/app/server/agent/mcp-server.ts" : join(projectRoot, "server/agent/mcp-server.ts");
+
+  const dockerEnv = useDocker
+    ? {
+        MCP_HOST: "host.docker.internal",
+        NODE_PATH: "/app/node_modules",
+        ...collectMcpToolSentinelEnv(),
+      }
+    : {};
+
+  // Bearer token for MCP subprocess to call /api/* back to this server
+  // (#272). The MCP bridge also has a file-read fallback from
+  // <workspace>/.session-token, but env is faster and works in Docker
+  // where the token file may not be bind-mounted.
+  const token = getCurrentToken();
+  const authEnv = token ? { MULMOCLAUDE_AUTH_TOKEN: token } : {};
+
+  return {
+    command,
+    args: [mcpServerPath],
+    env: {
+      SESSION_ID: chatSessionId,
+      PORT: String(port),
+      PLUGIN_NAMES: activePlugins.join(","),
+      ROLE_IDS: roleIds.join(","),
+      ...authEnv,
+      ...dockerEnv,
+    },
+  };
+}
+
+// Never let a user-defined server shadow the built-in internal bridge —
+// even if they pick "mulmoclaude" as the id. Drop the entry silently:
+// the UI already validates ids against the slug pattern, so this is
+// defence-in-depth.
+function excludeReservedKeys(servers: Record<string, McpServerSpec>): Record<string, McpServerSpec> {
+  const out: Record<string, McpServerSpec> = {};
+  for (const [id, spec] of Object.entries(servers)) {
+    if (id === "mulmoclaude") continue;
+    out[id] = spec;
+  }
+  return out;
+}
+
+export function buildMcpConfig(params: McpConfigParams): object {
+  const { chatSessionId, port, activePlugins, roleIds, useDocker = false, userServers = {} } = params;
+  return {
+    mcpServers: {
+      mulmoclaude: buildMulmoclaudeServer({
+        chatSessionId,
+        port,
+        activePlugins,
+        roleIds,
+        useDocker,
+      }),
+      ...excludeReservedKeys(userServers),
+    },
+  };
+}
+
+// User-facing `mcp__<server>` wildcard form for --allowedTools. Enabled
+// HTTP servers always participate; stdio servers only participate when
+// we're running natively (since the sandbox image is minimal in Docker).
+export function userServerAllowedToolNames(userServers: Record<string, McpServerSpec>, useDocker: boolean): string[] {
+  const names: string[] = [];
+  for (const [id, spec] of Object.entries(userServers)) {
+    if (spec.enabled === false) continue;
+    // Stdio servers are dropped under Docker because the sandbox
+    // image is too minimal to run most of them (see #162).
+    if (spec.type === "stdio" && useDocker) continue;
+    names.push(`mcp__${id}`);
+  }
+  return names;
+}
+
+export interface CliArgsParams {
+  systemPrompt: string;
+  activePlugins: string[];
+  claudeSessionId?: string;
+  mcpConfigPath?: string;
+  // Web UI-managed extension of the allowed-tools list. Merged with
+  // BASE_ALLOWED_TOOLS and the mcp__mulmoclaude__ plugin names.
+  extraAllowedTools?: string[];
+}
+
+export function buildCliArgs(params: CliArgsParams): string[] {
+  const { systemPrompt, activePlugins, claudeSessionId, mcpConfigPath, extraAllowedTools = [] } = params;
+
+  const mcpToolNames = activePlugins.map((p) => `mcp__mulmoclaude__${p}`);
+  const allowedTools = [...BASE_ALLOWED_TOOLS, ...extraAllowedTools, ...mcpToolNames];
+
+  // stream-json input mode: the user message is streamed through
+  // stdin (see `writeUserMessage` in server/agent.ts) rather than
+  // passed as a `-p <text>` argument. This path is required so that
+  // Claude resolves slash-command invocations (e.g. `/shiritori` from
+  // the manageSkills Run button) against `~/.claude/skills/`. In the
+  // old `-p <text>` mode the CLI treats the message as literal text
+  // and "/shiritori" never reaches the skill resolver.
+  const args = [
+    "--output-format",
+    "stream-json",
+    "--input-format",
+    "stream-json",
+    "--include-partial-messages",
+    "--verbose",
+    "--system-prompt",
+    systemPrompt,
+    "--allowedTools",
+    allowedTools.join(","),
+    "-p",
+  ];
+
+  if (claudeSessionId) {
+    args.push("--resume", claudeSessionId);
+  }
+
+  if (mcpConfigPath) {
+    args.push("--mcp-config", mcpConfigPath);
+  }
+
+  return args;
+}
+
+/** JSON line to write to the Claude CLI's stdin when running in
+ *  stream-json input mode. One line per user turn.
+ *
+ *  Supported attachment types:
+ *  - `image/*` → vision content blocks (`type: "image"`)
+ *  - `application/pdf` → document content blocks (`type: "document"`)
+ *  - `text/*`, JSON, XML, YAML, CSV → decoded UTF-8 → text block
+ *  - DOCX → mammoth text extraction → text block
+ *  - XLSX → xlsx CSV extraction → text block
+ *  - PPTX → libreoffice PDF conversion → document block (Docker only)
+ *  - Other MIME types → skipped with a console hint.
+ *
+ *  Without attachments, content is a plain string (smaller,
+ *  backward-compatible). */
+export async function buildUserMessageLine(message: string, attachments?: Attachment[]): Promise<string> {
+  const all = attachments ?? [];
+  if (all.length === 0) {
+    return (
+      JSON.stringify({
+        type: "user",
+        message: { role: "user", content: message },
+      }) + "\n"
+    );
+  }
+
+  const blocks: Array<Record<string, unknown>> = [];
+  const skippedReasons: string[] = [];
+
+  for (const att of all) {
+    // Native types: image and PDF go directly as content blocks
+    if (isNativeAttachmentMime(att.mimeType)) {
+      blocks.push(buildNativeBlock(att));
+      continue;
+    }
+    // Convertible types: text, docx, xlsx, pptx
+    const result = await convertAttachment(att);
+    if (result.kind === "converted") {
+      blocks.push(...result.blocks);
+    } else {
+      skippedReasons.push(result.reason);
+    }
+  }
+
+  if (skippedReasons.length > 0) {
+    log.warn("agent", "skipping unsupported attachment(s)", {
+      count: skippedReasons.length,
+      reasons: skippedReasons,
+    });
+  }
+
+  blocks.push({ type: "text", text: message });
+  return (
+    JSON.stringify({
+      type: "user",
+      message: { role: "user", content: blocks },
+    }) + "\n"
+  );
+}
+
+function buildNativeBlock(att: Attachment): Record<string, unknown> {
+  const blockType = isImageMime(att.mimeType) ? "image" : "document";
+  return {
+    type: blockType,
+    source: {
+      type: "base64",
+      media_type: att.mimeType,
+      data: att.data,
+    },
+  };
+}
+
+export interface McpConfigPaths {
+  // Where the file is actually written on the host filesystem.
+  hostPath: string;
+  // What gets passed to claude --mcp-config (container path under
+  // docker, identical to hostPath when running natively).
+  argPath: string;
+}
+
+export function resolveMcpConfigPaths(opts: { workspacePath: string; sessionId: string; useDocker: boolean }): McpConfigPaths {
+  if (opts.useDocker) {
+    const hostPath = join(opts.workspacePath, ".mulmoclaude", `mcp-${opts.sessionId}.json`);
+    const argPath = `${CONTAINER_WORKSPACE_PATH}/.mulmoclaude/mcp-${opts.sessionId}.json`;
+    return { hostPath, argPath };
+  }
+  const hostPath = join(tmpdir(), `mulmoclaude-mcp-${opts.sessionId}.json`);
+  return { hostPath, argPath: hostPath };
+}
+
+// Mirror NodeJS.Platform — re-declared so the file doesn't need a
+// `NodeJS` global reference, which the no-undef rule doesn't see in
+// type-only positions.
+export type Platform = "aix" | "android" | "darwin" | "freebsd" | "haiku" | "linux" | "openbsd" | "sunos" | "win32" | "cygwin" | "netbsd";
+
+export interface DockerSpawnArgsParams {
+  workspacePath: string;
+  cliArgs: string[];
+  uid: number;
+  gid: number;
+  platform: Platform;
+  projectRoot?: string;
+  homeDir?: string;
+  /** Extra `-v` / `-e` tokens for opt-in host credentials (#259).
+   *  Built by `resolveSandboxAuth` in `sandboxMounts.ts`. Default []. */
+  sandboxAuthArgs?: readonly string[];
+  /** Whether SSH agent forwarding is active. When true, the container
+   *  uses the entrypoint (root → setup → setpriv drop) instead of
+   *  `--user`, and adds the minimum capabilities the entrypoint needs.
+   *  When false (default), `--user uid:gid --cap-drop ALL` with zero
+   *  capabilities — identical to the pre-#259 security posture. */
+  sshAgentForward?: boolean;
+}
+
+// Pure helper that returns the full `docker run ... claude <args>`
+// argv array. Extracted from runAgent so the long flag list can be
+// inspected and tested without spawning a real subprocess.
+export function buildDockerSpawnArgs(params: DockerSpawnArgsParams): string[] {
+  const {
+    workspacePath,
+    cliArgs,
+    uid,
+    gid,
+    platform,
+    projectRoot = process.cwd(),
+    homeDir = homedir(),
+    sandboxAuthArgs = [],
+    sshAgentForward = false,
+  } = params;
+  const toDockerPath = (p: string): string => p.replace(/\\/g, "/");
+  const extraHosts: string[] = platform === "linux" ? ["--add-host", "host.docker.internal:host-gateway"] : [];
+
+  return [
+    "run",
+    "--rm",
+    // -i keeps the container's stdin open so the stream-json user
+    // message (see buildUserMessageLine) can flow through. Without
+    // this Docker detaches stdin and the CLI reads EOF on startup.
+    "-i",
+    "--cap-drop",
+    "ALL",
+    // When SSH agent forwarding is active, the entrypoint needs root
+    // to fix /etc/passwd, chown /home/node, and chmod the socket.
+    // These 5 caps are the minimum set; setpriv --inh-caps=-all
+    // drops them on exec so Claude runs with zero capabilities.
+    //
+    // When SSH is OFF, use the simpler `--user uid:gid` which runs
+    // the entire container as the host user — zero caps from the
+    // start, identical to the pre-#259 security posture.
+    ...(sshAgentForward
+      ? [
+          "--cap-add",
+          "CHOWN",
+          "--cap-add",
+          "FOWNER",
+          "--cap-add",
+          "DAC_OVERRIDE",
+          "--cap-add",
+          "SETUID",
+          "--cap-add",
+          "SETGID",
+          "-e",
+          `HOST_UID=${uid}`,
+          "-e",
+          `HOST_GID=${gid}`,
+        ]
+      : ["--user", `${uid}:${gid}`]),
+    "-e",
+    "HOME=/home/node",
+    "-v",
+    `${toDockerPath(projectRoot)}/node_modules:/app/node_modules:ro`,
+    "-v",
+    `${toDockerPath(projectRoot)}/server:/app/server:ro`,
+    "-v",
+    `${toDockerPath(projectRoot)}/src:/app/src:ro`,
+    "-v",
+    `${toDockerPath(projectRoot)}/packages:/app/packages:ro`,
+    "-v",
+    `${toDockerPath(workspacePath)}:${CONTAINER_WORKSPACE_PATH}`,
+    "-v",
+    `${toDockerPath(homeDir)}/.claude:/home/node/.claude`,
+    "-v",
+    `${toDockerPath(homeDir)}/.claude.json:/home/node/.claude.json`,
+    ...sandboxAuthArgs,
+    ...extraHosts,
+    "mulmoclaude-sandbox",
+    "claude",
+    ...cliArgs,
+  ];
+}

package/server/agent/index.ts

@@ -0,0 +1,260 @@
+import { spawn, type ChildProcessByStdio } from "child_process";
+import { mkdir, writeFile, unlink } from "fs/promises";
+import { dirname } from "path";
+import type { Readable, Writable } from "stream";
+import { isDockerAvailable } from "../system/docker.js";
+import { refreshCredentials } from "../system/credentials.js";
+import { loadMcpConfig, loadSettings } from "../system/config.js";
+import type { Role } from "../../src/config/roles.js";
+import { loadAllRoles } from "../workspace/roles.js";
+import { buildSystemPrompt } from "./prompt.js";
+import {
+  CONTAINER_WORKSPACE_PATH,
+  buildCliArgs,
+  buildDockerSpawnArgs,
+  buildMcpConfig,
+  buildUserMessageLine,
+  getActivePlugins,
+  prepareUserServers,
+  resolveMcpConfigPaths,
+  userServerAllowedToolNames,
+} from "./config.js";
+import type { Attachment } from "@mulmobridge/protocol";
+import { createStreamParser, type AgentEvent, type RawStreamEvent } from "./stream.js";
+import { log } from "../system/logger/index.js";
+import { EVENT_TYPES } from "../../src/types/events.js";
+import { env } from "../system/env.js";
+import { resolveSandboxAuth } from "./sandboxMounts.js";
+import { getCachedReferenceDirs, referenceDirMountArgs } from "../workspace/reference-dirs.js";
+
+type ClaudeProc = ChildProcessByStdio<Writable, Readable, Readable>;
+
+function spawnClaude(useDocker: boolean, workspacePath: string, cliArgs: string[]): ClaudeProc {
+  if (!useDocker) {
+    return spawn("claude", cliArgs, {
+      cwd: workspacePath,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+  }
+  const sandboxAuth = resolveSandboxAuth({
+    sshAgentForward: env.sandboxSshAgentForward,
+    sshAllowedHosts: env.sandboxSshAllowedHosts,
+    configMountNames: env.sandboxMountConfigs,
+    sshAuthSock: process.env.SSH_AUTH_SOCK,
+  });
+  const refDirArgs = referenceDirMountArgs(getCachedReferenceDirs());
+  const dockerArgs = buildDockerSpawnArgs({
+    workspacePath,
+    cliArgs,
+    uid: process.getuid?.() ?? 1000,
+    gid: process.getgid?.() ?? 1000,
+    platform: process.platform,
+    sandboxAuthArgs: [...sandboxAuth.args, ...refDirArgs],
+    sshAgentForward: env.sandboxSshAgentForward,
+  });
+  return spawn("docker", dockerArgs, { stdio: ["pipe", "pipe", "pipe"] });
+}
+
+// Track MCP tool usage to detect silent MCP server failures.
+// If ToolSearch was called but no mcp__* tool was ever invoked,
+// the MCP server likely crashed on startup (e.g. module resolution
+// failure inside Docker). See #430.
+function createMcpTracker() {
+  let toolSearchCalled = false;
+  let mcpToolCalled = false;
+  return {
+    track(event: AgentEvent) {
+      if (event.type !== EVENT_TYPES.toolCall) return;
+      if (event.toolName === "ToolSearch") toolSearchCalled = true;
+      if (event.toolName.startsWith("mcp__")) mcpToolCalled = true;
+    },
+    logIfSuspicious() {
+      if (toolSearchCalled && !mcpToolCalled) {
+        log.warn(
+          "agent",
+          "ToolSearch was used but no MCP tool was called — the MCP server may have crashed. " +
+            "Check Docker volume mounts and package.json exports. " +
+            "Run: npx tsx --test test/agent/test_mcp_docker_smoke.ts",
+        );
+      }
+    },
+  };
+}
+
+async function* readAgentEvents(proc: ClaudeProc): AsyncGenerator<AgentEvent> {
+  let stderrOutput = "";
+  let stderrBuffer = "";
+  proc.stderr.on("data", (chunk: Buffer) => {
+    const text = chunk.toString();
+    stderrOutput += text;
+    stderrBuffer += text;
+    const lines = stderrBuffer.split("\n");
+    stderrBuffer = lines.pop() ?? "";
+    for (const line of lines) {
+      if (line.trim()) log.error("agent-stderr", line);
+    }
+  });
+
+  // Stateful parser tracks whether text was already streamed via
+  // assistant content blocks so the final `result` event's duplicate
+  // text is suppressed. See createStreamParser() in stream.ts.
+  const parser = createStreamParser();
+
+  const mcpTracker = createMcpTracker();
+
+  let buffer = "";
+  for await (const chunk of proc.stdout) {
+    buffer += (chunk as Buffer).toString();
+    const lines = buffer.split("\n");
+    buffer = lines.pop() ?? "";
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      let event: RawStreamEvent;
+      try {
+        event = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      for (const agentEvent of parser.parse(event)) {
+        mcpTracker.track(agentEvent);
+        yield agentEvent;
+      }
+    }
+  }
+
+  const exitCode = await new Promise<number>((resolve) => proc.on("close", resolve));
+
+  if (stderrBuffer.trim()) log.error("agent-stderr", stderrBuffer);
+  log.info("agent", "claude exited", { exitCode });
+  mcpTracker.logIfSuspicious();
+
+  if (exitCode !== 0) {
+    yield {
+      type: EVENT_TYPES.error,
+      message: stderrOutput || `claude exited with code ${exitCode}`,
+    };
+  }
+}
+
+export interface RunAgentOptions {
+  message: string;
+  role: Role;
+  workspacePath: string;
+  sessionId: string;
+  port: number;
+  claudeSessionId?: string;
+  /** When aborted, the spawned Claude CLI process is killed. */
+  abortSignal?: AbortSignal;
+}
+
+export async function* runAgent(
+  message: string,
+  role: Role,
+  workspacePath: string,
+  sessionId: string,
+  port: number,
+  claudeSessionId?: string,
+  abortSignal?: AbortSignal,
+  attachments?: Attachment[],
+): AsyncGenerator<AgentEvent> {
+  const activePlugins = getActivePlugins(role);
+  const useDocker = await isDockerAvailable();
+
+  // User-defined MCP servers are read per invocation so Settings UI
+  // changes apply immediately. Disabled / malformed entries get
+  // filtered by prepareUserServers; remaining servers are merged into
+  // the --mcp-config payload below.
+  const userMcpRaw = loadMcpConfig().mcpServers;
+  const userServers = prepareUserServers(userMcpRaw, useDocker, workspacePath);
+  const hasUserServers = Object.keys(userServers).length > 0;
+  const hasMcp = activePlugins.length > 0 || hasUserServers;
+
+  // On macOS sandbox, always refresh credentials from Keychain before each
+  // agent run so that expired OAuth tokens are replaced transparently.
+  if (useDocker && process.platform === "darwin") {
+    await refreshCredentials();
+  }
+
+  const fullSystemPrompt = buildSystemPrompt({
+    role,
+    workspacePath: useDocker ? CONTAINER_WORKSPACE_PATH : workspacePath,
+    useDocker,
+  });
+
+  // In debug mode (--debug), dump the full system prompt on the first
+  // message of each session so developers can inspect what the LLM sees.
+  if (!claudeSessionId && process.argv.includes("--debug")) {
+    log.info("agent", "system prompt for new session:\n" + fullSystemPrompt);
+  }
+
+  const mcpPaths = resolveMcpConfigPaths({
+    workspacePath,
+    sessionId,
+    useDocker,
+  });
+  if (useDocker) {
+    await mkdir(dirname(mcpPaths.hostPath), { recursive: true });
+  }
+
+  if (hasMcp) {
+    const mcpConfig = buildMcpConfig({
+      chatSessionId: sessionId,
+      port,
+      activePlugins,
+      roleIds: loadAllRoles().map((r) => r.id),
+      useDocker,
+      userServers,
+    });
+    await writeFile(mcpPaths.hostPath, JSON.stringify(mcpConfig, null, 2));
+  }
+
+  // Fresh read on every invocation so the Settings UI can change
+  // allowedTools / MCP servers without a server restart.
+  const settings = loadSettings();
+  const userServerAllowedTools = userServerAllowedToolNames(userServers, useDocker);
+
+  const cliArgs = buildCliArgs({
+    systemPrompt: fullSystemPrompt,
+    activePlugins,
+    claudeSessionId,
+    mcpConfigPath: hasMcp ? mcpPaths.argPath : undefined,
+    extraAllowedTools: [...settings.extraAllowedTools, ...userServerAllowedTools],
+  });
+
+  // Don't persist raw sessionId into log sinks (esp. the retained
+  // file sink). A boolean presence flag is enough for operational
+  // debugging and avoids writing identifiers that route back to a
+  // specific session into long-lived log files.
+  log.info("agent", "spawning claude", {
+    roleId: role.id,
+    useDocker,
+    hasMcp,
+    resumed: Boolean(claudeSessionId),
+    hasSessionId: Boolean(sessionId),
+  });
+  const proc = spawnClaude(useDocker, workspacePath, cliArgs);
+
+  // stream-json input mode: stream the user turn as a single JSON
+  // line to stdin, then close the pipe so the CLI knows no further
+  // turns are coming. Writing before attaching the abort handler
+  // is fine — if the write fails because the process already died
+  // for other reasons, the `readAgentEvents` loop below surfaces it.
+  const messageLine = await buildUserMessageLine(message, attachments);
+  proc.stdin.write(messageLine);
+  proc.stdin.end();
+
+  // If an abort signal is provided, kill the process when it fires.
+  const onAbort = () => {
+    if (!proc.killed) proc.kill();
+  };
+  abortSignal?.addEventListener("abort", onAbort, { once: true });
+
+  try {
+    yield* readAgentEvents(proc);
+  } finally {
+    abortSignal?.removeEventListener("abort", onAbort);
+    if (!proc.killed) proc.kill();
+    if (hasMcp) unlink(mcpPaths.hostPath).catch(() => {});
+  }
+}