@desplega.ai/agent-swarm 1.172.0 → 2.0.0

package/src/tests/chat-sdk-webhook-telegram.test.ts

@@ -0,0 +1,200 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import {
+  startTelegramBotApiMock,
+  type TelegramBotApiMock,
+} from "../../scripts/dev/telegram-bot-api-mock";
+import { closeDb, createAgent, getDbClient, initDb } from "../be/db";
+import { handleWebhooks } from "../http/webhooks";
+import { drainBackground } from "../integrations/chat-sdk/background";
+import { getChatSdkHealth, startChatSdk, stopChatSdk } from "../integrations/chat-sdk/runtime";
+import { flushAllChatBuffers } from "../integrations/chat-sdk/thread-buffer";
+import { getEnabledCapabilities } from "../server";
+import privateText from "./fixtures/chat-sdk/telegram-private-text.json";
+
+const TEST_DB_PATH = "./test-chat-sdk-telegram.sqlite";
+const SECRET = "s";
+const ENV_KEYS = ["CHAT_SDK_ENABLED", "CHAT_SDK_ADAPTERS", "CHAT_SDK_API_URL_OVERRIDES"];
+const savedEnv = new Map(ENV_KEYS.map((key) => [key, process.env[key]]));
+
+let mock: TelegramBotApiMock;
+let leadId: string;
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    await unlink(`${TEST_DB_PATH}${suffix}`).catch(() => {});
+  }
+}
+
+/** Minimal fake req/res to drive handleWebhooks without a live server. */
+function fakeReqRes(path: string, rawBody: string, headers: Record<string, string>) {
+  const rawHeaders = Object.entries(headers).flat();
+  const req = {
+    method: "POST",
+    url: path,
+    headers: Object.fromEntries(Object.entries(headers).map(([k, v]) => [k.toLowerCase(), v])),
+    rawHeaders,
+    async *[Symbol.asyncIterator]() {
+      yield Buffer.from(rawBody);
+    },
+  } as unknown as IncomingMessage;
+
+  const captured = { status: 0, body: "" };
+  const res = {
+    writeHead(status: number) {
+      captured.status = status;
+      return this;
+    },
+    end(chunk?: string | Buffer) {
+      if (chunk) captured.body = chunk.toString();
+      return this;
+    },
+  } as unknown as ServerResponse;
+
+  return { req, res, captured };
+}
+
+async function post(adapter: string, body: unknown, headers: Record<string, string>) {
+  const path = `/api/integrations/chat/${adapter}/webhook`;
+  const { req, res, captured } = fakeReqRes(path, JSON.stringify(body), {
+    "Content-Type": "application/json",
+    ...headers,
+  });
+  const handled = await handleWebhooks(req, res, path.split("/").filter(Boolean));
+  expect(handled).toBe(true);
+  return captured;
+}
+
+beforeAll(async () => {
+  await removeDbFiles();
+  initDb(TEST_DB_PATH);
+  const lead = await createAgent({
+    id: crypto.randomUUID(),
+    name: "ChatLead",
+    isLead: true,
+    status: "idle",
+  });
+  leadId = lead.id;
+  mock = startTelegramBotApiMock();
+  process.env.CHAT_SDK_ENABLED = "true";
+  process.env.CHAT_SDK_ADAPTERS = JSON.stringify({
+    telegram: { botToken: "t", secretToken: SECRET, mode: "webhook" },
+  });
+  process.env.CHAT_SDK_API_URL_OVERRIDES = JSON.stringify({ telegram: mock.url });
+  await startChatSdk();
+});
+
+afterAll(async () => {
+  await stopChatSdk();
+  mock.stop();
+  for (const [key, value] of savedEnv) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+  closeDb();
+  await removeDbFiles();
+});
+
+describe("Chat SDK Telegram webhook", () => {
+  test("the adapter starts healthy against the mock Bot API", () => {
+    expect(getChatSdkHealth().telegram?.status).toBe("ok");
+    expect(mock.calls.some((call) => call.method === "getMe")).toBe(true);
+  });
+
+  test("a wrong secret token is rejected with 401", async () => {
+    const captured = await post("telegram", privateText, {
+      "X-Telegram-Bot-Api-Secret-Token": "wrong",
+    });
+    expect(captured.status).toBe(401);
+  });
+
+  test("a body above 1 MiB is rejected with 413 before the adapter runs", async () => {
+    const path = "/api/integrations/chat/telegram/webhook";
+    const segments = path.split("/").filter(Boolean);
+    const oversized = "x".repeat(1024 * 1024 + 1);
+    const secretHeader = { "X-Telegram-Bot-Api-Secret-Token": SECRET };
+    const sentBefore = mock.calls.length;
+
+    // Declared up front: rejected before any chunk is read.
+    const declared = fakeReqRes(path, "{}", {
+      ...secretHeader,
+      "Content-Length": String(oversized.length),
+    });
+    expect(await handleWebhooks(declared.req, declared.res, segments)).toBe(true);
+    expect(declared.captured.status).toBe(413);
+
+    // Streamed without Content-Length: rejected once the cap is crossed.
+    const streamed = fakeReqRes(path, oversized, secretHeader);
+    expect(await handleWebhooks(streamed.req, streamed.res, segments)).toBe(true);
+    expect(streamed.captured.status).toBe(413);
+    expect(JSON.parse(streamed.captured.body).error).toContain("Payload too large");
+    expect(mock.calls.length).toBe(sentBefore);
+  });
+
+  test("an unconfigured adapter answers 404", async () => {
+    const captured = await post("discord", {}, {});
+    expect(captured.status).toBe(404);
+  });
+
+  test("a private-chat text update creates one Lead task with a chat-sdk contextKey", async () => {
+    const captured = await post("telegram", privateText, {
+      "X-Telegram-Bot-Api-Secret-Token": SECRET,
+    });
+    expect(captured.status).toBe(200);
+    expect(await drainBackground(5_000)).toBe(true);
+    // Messages wait in the thread buffer; flush it instead of waiting 10 s.
+    await flushAllChatBuffers();
+    expect(await drainBackground(5_000)).toBe(true);
+
+    const tasks = await getDbClient().query<{
+      id: string;
+      source: string;
+      contextKey: string;
+      agentId: string | null;
+      task: string;
+      taskType: string;
+    }>(
+      "SELECT id, source, contextKey, agentId, task, taskType FROM agent_tasks WHERE source = 'chat'",
+    );
+    expect(tasks).toHaveLength(1);
+    const [task] = tasks;
+    expect(task!.contextKey.startsWith("task:chat-sdk:telegram:")).toBe(true);
+    expect(task!.agentId).toBe(leadId);
+    expect(task!.taskType).toBe("chat-inbound");
+    expect(task!.task).toContain("summarize the open tasks");
+
+    const subscriptions = await getDbClient().query<{ thread_id: string }>(
+      "SELECT thread_id FROM chat_subscriptions",
+    );
+    expect(subscriptions.map((row) => row.thread_id)).toContain("telegram:555001");
+  });
+
+  test("a redelivered update is deduplicated", async () => {
+    const captured = await post("telegram", privateText, {
+      "X-Telegram-Bot-Api-Secret-Token": SECRET,
+    });
+    expect(captured.status).toBe(200);
+    expect(await drainBackground(5_000)).toBe(true);
+    await flushAllChatBuffers();
+    const row = await getDbClient().get<{ n: number }>(
+      "SELECT COUNT(*) AS n FROM agent_tasks WHERE source = 'chat'",
+    );
+    expect(row?.n).toBe(1);
+  });
+});
+
+describe("chat-sdk capability", () => {
+  test("is advertised only when CHAT_SDK_ENABLED is true", () => {
+    const previous = process.env.CHAT_SDK_ENABLED;
+    try {
+      process.env.CHAT_SDK_ENABLED = "true";
+      expect(getEnabledCapabilities()).toContain("chat-sdk");
+      process.env.CHAT_SDK_ENABLED = "false";
+      expect(getEnabledCapabilities()).not.toContain("chat-sdk");
+    } finally {
+      if (previous === undefined) delete process.env.CHAT_SDK_ENABLED;
+      else process.env.CHAT_SDK_ENABLED = previous;
+    }
+  });
+});

package/src/tests/claude-adapter-binary.test.ts

@@ -38,6 +38,7 @@ import {
 } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { WORKSPACE_CLAUDE_MD_PATH } from "../commands/profile-sync";
 import {
   ClaudeAdapter,
   parseClaudeBinary,
@@ -48,6 +49,7 @@ import {
   resolveClaudeBridgeEnabled,
   resolveClaudeTrustDirs,
 } from "../providers/claude-adapter";
+import { ClaudeSettingsConfigError, userClaudeMdExclude } from "../providers/claude-flag-settings";
 import type { ProviderSessionConfig } from "../providers/types";
 import { setFlockForTests } from "../utils/file-lock";
 import { holdFileLock } from "./fixtures/hold-file-lock";
@@ -694,6 +696,8 @@ describe("CLAUDE_BINARY env override", () => {
   let spawnSpy: ReturnType<typeof spyOn>;
   let whichSpy: ReturnType<typeof spyOn>;
   let spawnedArgs: Array<readonly string[]>;
+  /** Every non-git spawn, including the `--version` probe. */
+  let claudeSpawns: Array<readonly string[]>;
   let spawnedEnvs: Array<Record<string, string> | undefined>;
 
   beforeEach(async () => {
@@ -712,9 +716,11 @@ describe("CLAUDE_BINARY env override", () => {
     process.env.CLAUDE_CODE_OAUTH_TOKEN = "example-test-token";
 
     spawnedArgs = [];
+    claudeSpawns = [];
     spawnedEnvs = [];
     spawnSpy = spyOn(Bun, "spawn").mockImplementation(((cmd: readonly string[], opts?: unknown) => {
       if (isGit(cmd)) return (realSpawn as (...a: unknown[]) => unknown)(cmd, opts);
+      claudeSpawns.push(cmd);
       if (cmd.at(-1) !== "--version") {
         spawnedArgs.push(cmd);
         spawnedEnvs.push((opts as { env?: Record<string, string> } | undefined)?.env);
@@ -769,6 +775,144 @@ describe("CLAUDE_BINARY env override", () => {
     expect(argv[0]).toBe("claude");
   });
 
+  test("excludes both on-disk agent CLAUDE.md copies from Claude's memory load", async () => {
+    const adapter = new ClaudeAdapter();
+    await createCompletedSession(adapter, makeConfig());
+
+    const argv = spawnedArgs[0];
+    const at = argv.indexOf("--settings");
+    expect(at).toBeGreaterThan(0);
+    expect(JSON.parse(argv[at + 1] ?? "")).toEqual({
+      claudeMdExcludes: [WORKSPACE_CLAUDE_MD_PATH, userClaudeMdExclude()],
+    });
+  });
+
+  test("merges caller --settings from additionalArgs and CLAUDE_BINARY into one flag", async () => {
+    const settingsDir = await mkdtemp(join(tmpdir(), "claude-settings-merge-"));
+    try {
+      await writeFile(
+        join(settingsDir, "caller.json"),
+        JSON.stringify({ model: "from-file", claudeMdExcludes: ["/repo/CLAUDE.md"] }),
+      );
+      process.env.CLAUDE_BINARY = `claude --settings=${join(settingsDir, "caller.json")}`;
+      const adapter = new ClaudeAdapter();
+      await createCompletedSession(
+        adapter,
+        makeConfig({
+          cwd: settingsDir,
+          additionalArgs: [
+            "--settings",
+            JSON.stringify({
+              env: { X: "kept" },
+              claudeMdExcludes: [WORKSPACE_CLAUDE_MD_PATH, "/other/CLAUDE.md"],
+            }),
+            "--max-turns",
+            "3",
+          ],
+        }),
+      );
+
+      const argv = spawnedArgs[0];
+      const settingsFlags = argv.filter(
+        (arg) => arg === "--settings" || arg.startsWith("--settings="),
+      );
+      expect(settingsFlags).toEqual(["--settings"]);
+      expect(JSON.parse(argv[argv.indexOf("--settings") + 1] ?? "")).toEqual({
+        model: "from-file",
+        env: { X: "kept" },
+        claudeMdExcludes: [
+          "/repo/CLAUDE.md",
+          WORKSPACE_CLAUDE_MD_PATH,
+          "/other/CLAUDE.md",
+          userClaudeMdExclude(),
+        ],
+      });
+      expect(argv[0]).toBe("claude");
+      expect(argv.slice(argv.indexOf("--max-turns"), argv.indexOf("--max-turns") + 2)).toEqual([
+        "--max-turns",
+        "3",
+      ]);
+      // The version probe runs with the same stripped prefix and merged settings.
+      const probe = claudeSpawns.find((cmd) => cmd.at(-1) === "--version") ?? [];
+      expect(probe).toEqual([
+        "claude",
+        "--settings",
+        argv[argv.indexOf("--settings") + 1] ?? "",
+        "--version",
+      ]);
+    } finally {
+      await rm(settingsDir, { recursive: true, force: true });
+    }
+  });
+
+  test("invalid caller --settings refuses to start: no Claude child spawns", async () => {
+    const settingsDir = await mkdtemp(join(tmpdir(), "claude-settings-invalid-"));
+    // Built at runtime so no single source literal looks like a credential.
+    const sentinel = ["settings", "sentinel", crypto.randomUUID()].join("-");
+    try {
+      await writeFile(join(settingsDir, "broken.json"), "{nope");
+      await writeFile(join(settingsDir, "array.json"), "[1]");
+      const cases: [string[], string][] = [
+        [["--settings", "missing.json"], "cannot be read (ENOENT)"],
+        [["--settings", "broken.json"], "is not valid JSON"],
+        [["--settings", `{"env":{"TOKEN":"${sentinel}"`], "is not valid JSON"],
+        [["--settings=array.json"], "is not a JSON object"],
+        [["--settings", "--max-turns", "3"], "--settings has no value"],
+        [["--settings", '--settings={"model":"x"}'], "--settings has no value"],
+      ];
+      for (const [additionalArgs, message] of cases) {
+        claudeSpawns = [];
+        const adapter = new ClaudeAdapter();
+        const error = await adapter
+          .createSession(makeConfig({ cwd: settingsDir, additionalArgs }))
+          .then(
+            () => undefined,
+            (err: unknown) => err,
+          );
+        expect(error).toBeInstanceOf(ClaudeSettingsConfigError);
+        expect((error as Error).message).toContain(message);
+        expect((error as Error).message).not.toContain(sentinel);
+        // Counts the `--version` probe too: validation runs before every spawn.
+        expect(claudeSpawns).toEqual([]);
+        // ...and before the trust pre-seed writes ~/.claude.json.
+        expect(await Bun.file(join(homeDir, ".claude.json")).exists()).toBeFalse();
+      }
+    } finally {
+      await rm(settingsDir, { recursive: true, force: true });
+    }
+  });
+
+  test("invalid CLAUDE_BINARY prefix --settings never reaches logs, errors, or a spawn", async () => {
+    const sentinel = ["prefix", "sentinel", crypto.randomUUID()].join("-");
+    const inline = `{"env":{"TOKEN":"${sentinel}"`;
+    const logged: string[] = [];
+    const capture = (...args: unknown[]) => {
+      logged.push(args.map(String).join(" "));
+    };
+    const logSpy = spyOn(console, "log").mockImplementation(capture);
+    const warnSpy = spyOn(console, "warn").mockImplementation(capture);
+    const errorSpy = spyOn(console, "error").mockImplementation(capture);
+    try {
+      for (const binary of [`claude --settings=${inline}`, `claude --settings ${inline}`]) {
+        process.env.CLAUDE_BINARY = binary;
+        claudeSpawns = [];
+        const error = await new ClaudeAdapter().createSession(makeConfig()).then(
+          () => undefined,
+          (err: unknown) => err,
+        );
+        expect(error).toBeInstanceOf(ClaudeSettingsConfigError);
+        expect((error as Error).message).toContain("inline JSON is not valid JSON");
+        expect((error as Error).message).not.toContain(sentinel);
+        expect(claudeSpawns).toEqual([]);
+      }
+    } finally {
+      logSpy.mockRestore();
+      warnSpy.mockRestore();
+      errorSpy.mockRestore();
+    }
+    expect(logged.filter((line) => line.includes(sentinel))).toEqual([]);
+  });
+
   test("legacy bridge override: argv[0] comes from CLAUDE_BINARY", async () => {
     process.env.CLAUDE_BINARY = LEGACY_BRIDGE_COMPAT_BINARY;
 

package/src/tests/claude-flag-settings.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  ClaudeSettingsConfigError,
+  mergeClaudeSettingsArgs,
+  userClaudeMdExclude,
+  WORKSPACE_CLAUDE_MD_EXCLUDE,
+} from "../providers/claude-flag-settings";
+
+let directory: string;
+
+beforeEach(async () => {
+  directory = await mkdtemp(join(tmpdir(), "claude-flag-settings-"));
+});
+
+afterEach(async () => {
+  await rm(directory, { recursive: true, force: true });
+});
+
+describe("mergeClaudeSettingsArgs", () => {
+  test("no caller settings: args pass through, only the workspace exclusion", () => {
+    const merged = mergeClaudeSettingsArgs([["--max-turns", "3"]], directory);
+    expect(merged.argLists).toEqual([["--max-turns", "3"]]);
+    expect(merged.settings).toEqual({
+      claudeMdExcludes: [WORKSPACE_CLAUDE_MD_EXCLUDE, userClaudeMdExclude()],
+    });
+  });
+
+  test("strips both flag forms, keeps caller keys, unions and dedupes claudeMdExcludes", async () => {
+    await writeFile(
+      join(directory, "relative.json"),
+      JSON.stringify({ model: "file", claudeMdExcludes: ["/a/CLAUDE.md", "/a/CLAUDE.md"] }),
+    );
+    const merged = mergeClaudeSettingsArgs(
+      [
+        ["--settings", "relative.json"],
+        [
+          "--verbose",
+          `--settings=${JSON.stringify({ env: { X: "kept" }, claudeMdExcludes: [WORKSPACE_CLAUDE_MD_EXCLUDE, "/b/CLAUDE.md"] })}`,
+        ],
+      ],
+      directory,
+    );
+    expect(merged.argLists).toEqual([[], ["--verbose"]]);
+    expect(merged.settings).toEqual({
+      model: "file",
+      env: { X: "kept" },
+      claudeMdExcludes: [
+        "/a/CLAUDE.md",
+        WORKSPACE_CLAUDE_MD_EXCLUDE,
+        "/b/CLAUDE.md",
+        userClaudeMdExclude(),
+      ],
+    });
+  });
+
+  test("missing file, malformed JSON and non-object values refuse to start", async () => {
+    await writeFile(join(directory, "array.json"), "[1]");
+    await writeFile(join(directory, "broken.json"), "{nope");
+    const cases: [string[], string][] = [
+      [
+        ["--settings=missing.json"],
+        `file ${join(directory, "missing.json")} cannot be read (ENOENT)`,
+      ],
+      [["--settings", "broken.json"], `file ${join(directory, "broken.json")} is not valid JSON`],
+      [["--settings", "array.json"], "is not a JSON object"],
+    ];
+    for (const [args, message] of cases) {
+      expect(() => mergeClaudeSettingsArgs([args], directory)).toThrow(message);
+      expect(() => mergeClaudeSettingsArgs([args], directory)).toThrow(ClaudeSettingsConfigError);
+    }
+  });
+
+  test("malformed inline JSON error never echoes the value", () => {
+    let error: unknown;
+    try {
+      mergeClaudeSettingsArgs(
+        [["--settings", '{"env":{"TOKEN":"sk-ant-oat01-should-not-leak"', "--verbose"]],
+        directory,
+      );
+    } catch (err) {
+      error = err;
+    }
+    expect(error).toBeInstanceOf(ClaudeSettingsConfigError);
+    expect((error as Error).message).toContain("inline JSON is not valid JSON");
+    expect((error as Error).message).not.toContain("should-not-leak");
+  });
+
+  test("a missing value never swallows the next flag", () => {
+    for (const args of [
+      ["--settings"],
+      ["--settings="],
+      ["--settings", "--max-turns", "3"],
+      ["--settings", `--settings=${JSON.stringify({ model: "x" })}`],
+    ]) {
+      expect(() => mergeClaudeSettingsArgs([args], directory)).toThrow("--settings has no value");
+    }
+  });
+
+  test("consecutive valid settings flags merge in order", () => {
+    const merged = mergeClaudeSettingsArgs(
+      [["--settings", '{"model":"a"}', '--settings={"model":"b","env":{}}', "--max-turns", "3"]],
+      directory,
+    );
+    expect(merged.argLists).toEqual([["--max-turns", "3"]]);
+    expect(merged.settings).toEqual({
+      model: "b",
+      env: {},
+      claudeMdExcludes: [WORKSPACE_CLAUDE_MD_EXCLUDE, userClaudeMdExclude()],
+    });
+  });
+});

package/src/tests/claude-managed-adapter.test.ts

@@ -966,7 +966,7 @@ describe("ClaudeManagedAdapter (Phase 4) — repo provisioning + cost data", ()
     expect(getClaudeManagedModelPricing("claude-sonnet-5-5")).toEqual({
       inputPerMillion: 2.0,
       outputPerMillion: 10.0,
-      cacheReadPerMillion: 0.2,
+      cacheReadPerMillion: 0.1,
       cacheWritePerMillion: 2.5,
     });
     expect(getClaudeManagedModelPricing("claude-sonnet-5")).toEqual({

package/src/tests/claude-sdk-lifecycle.test.ts

@@ -1,8 +1,9 @@
-import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
 import { mkdtemp, readFile, realpath, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { ClaudeAdapter, getTaskFilePath } from "../providers/claude-adapter";
+import { userClaudeMdExclude } from "../providers/claude-flag-settings";
 import type { ProviderEvent, ProviderSessionConfig } from "../providers/types";
 import { CHILD_PROCESS_TEST_BUDGET_MS, runChild } from "./test-proc";
 
@@ -148,6 +149,152 @@ describe("Claude SDK production adapter lifecycle", () => {
             argument === "--system-prompt" && fixtureState.argv[index + 1] === "",
         ),
       ).toBeFalse();
+      // The SDK forwards `settings` as `--settings`: Claude skips both agent CLAUDE.md copies.
+      const settingsAt = fixtureState.argv.indexOf("--settings");
+      expect(settingsAt).toBeGreaterThan(-1);
+      expect(JSON.parse(fixtureState.argv[settingsAt + 1] ?? "")).toMatchObject({
+        claudeMdExcludes: ["/workspace/CLAUDE.md", userClaudeMdExclude()],
+      });
+    },
+    { timeout: CHILD_PROCESS_TEST_BUDGET_MS },
+  );
+
+  test(
+    "merges caller --settings from additionalArgs and CLAUDE_BINARY into the SDK's one flag",
+    async () => {
+      const directory = await temporaryDirectory();
+      const stateFile = join(directory, "settings-state.json");
+      const settingsFile = join(directory, "caller-settings.json");
+      await Bun.write(
+        settingsFile,
+        JSON.stringify({ model: "from-file", claudeMdExcludes: ["/repo/CLAUDE.md"] }),
+      );
+      const sessionConfig = config(directory, "queue", stateFile);
+      sessionConfig.env = {
+        ...sessionConfig.env,
+        CLAUDE_BINARY: `${process.execPath} ${fixturePath} --settings ${settingsFile}`,
+      };
+      sessionConfig.additionalArgs = [
+        `--settings=${JSON.stringify({ env: { X: "kept" }, claudeMdExcludes: ["/other/CLAUDE.md"] })}`,
+      ];
+      const session = await new ClaudeAdapter(async () => {}).createSession(sessionConfig);
+      // Queue mode records argv once it has the initial plus two queued messages.
+      await session.deliverSteering?.({ mode: "queue", text: "queued-message-a" });
+      await session.deliverSteering?.({ mode: "queue", text: "queued-message-b" });
+      await session.waitForCompletion();
+
+      await waitForFile(stateFile);
+      const { argv } = JSON.parse(await Bun.file(stateFile).text()) as { argv: string[] };
+      const settingsFlags = argv.filter(
+        (arg) => arg === "--settings" || arg.startsWith("--settings="),
+      );
+      expect(settingsFlags).toEqual(["--settings"]);
+      expect(JSON.parse(argv[argv.indexOf("--settings") + 1] ?? "")).toEqual({
+        model: "from-file",
+        env: { X: "kept" },
+        claudeMdExcludes: [
+          "/repo/CLAUDE.md",
+          "/other/CLAUDE.md",
+          "/workspace/CLAUDE.md",
+          userClaudeMdExclude(),
+        ],
+      });
+      expect(argv).not.toContain(settingsFile);
+      // The version probe carries the same merged settings value.
+      const spawns = (await Bun.file(`${stateFile}.spawns`).text())
+        .trim()
+        .split("\n")
+        .map((line) => JSON.parse(line) as string[]);
+      const probe = spawns.find((args) => args.at(-1) === "--version") ?? [];
+      expect(probe).toEqual([
+        "--settings",
+        argv[argv.indexOf("--settings") + 1] ?? "",
+        "--version",
+      ]);
+    },
+    { timeout: CHILD_PROCESS_TEST_BUDGET_MS },
+  );
+
+  test(
+    "invalid caller --settings refuses to start: no Claude child spawns",
+    async () => {
+      const directory = await temporaryDirectory();
+      // Built at runtime so no single source literal looks like a credential.
+      const sentinel = ["settings", "sentinel", crypto.randomUUID()].join("-");
+      await Bun.write(join(directory, "broken.json"), "{nope");
+      await Bun.write(join(directory, "array.json"), "[1]");
+      const cases: [string[], string][] = [
+        [["--settings", "missing.json"], "cannot be read (ENOENT)"],
+        [["--settings", "broken.json"], "is not valid JSON"],
+        [["--settings", `{"env":{"TOKEN":"${sentinel}"`], "is not valid JSON"],
+        [["--settings=array.json"], "is not a JSON object"],
+        [["--settings", "--max-turns", "3"], "--settings has no value"],
+        [["--settings", '--settings={"model":"x"}'], "--settings has no value"],
+      ];
+      for (const [index, [additionalArgs, message]] of cases.entries()) {
+        const stateFile = join(directory, `invalid-${index}.json`);
+        const sessionConfig = { ...config(directory, "cancel", stateFile), additionalArgs };
+        let summaries = 0;
+        const error = await new ClaudeAdapter(async () => {
+          summaries++;
+        })
+          .createSession(sessionConfig)
+          .then(
+            () => undefined,
+            (err: unknown) => err,
+          );
+
+        expect((error as Error).name).toBe("ClaudeSettingsConfigError");
+        expect((error as Error).message).toContain(message);
+        expect((error as Error).message).not.toContain(sentinel);
+        // The fixture records every start, the `--version` probe included.
+        expect(await Bun.file(`${stateFile}.spawns`).exists()).toBeFalse();
+        expect(summaries).toBe(0);
+        expect(
+          await Bun.file(getTaskFilePath(`${process.pid}-${sessionConfig.taskId}`)).exists(),
+        ).toBeFalse();
+      }
+    },
+    { timeout: CHILD_PROCESS_TEST_BUDGET_MS },
+  );
+
+  test(
+    "invalid CLAUDE_BINARY prefix --settings never reaches logs, errors, or a spawn",
+    async () => {
+      const directory = await temporaryDirectory();
+      const sentinel = ["prefix", "sentinel", crypto.randomUUID()].join("-");
+      const inline = `{"env":{"TOKEN":"${sentinel}"`;
+      const logged: string[] = [];
+      const capture = (...args: unknown[]) => {
+        logged.push(args.map(String).join(" "));
+      };
+      const logSpy = spyOn(console, "log").mockImplementation(capture);
+      const warnSpy = spyOn(console, "warn").mockImplementation(capture);
+      const errorSpy = spyOn(console, "error").mockImplementation(capture);
+      try {
+        for (const [index, flag] of [`--settings=${inline}`, `--settings ${inline}`].entries()) {
+          const stateFile = join(directory, `prefix-${index}.json`);
+          const sessionConfig = config(directory, "cancel", stateFile);
+          sessionConfig.env = {
+            ...sessionConfig.env,
+            CLAUDE_BINARY: `${process.execPath} ${fixturePath} ${flag}`,
+          };
+          const error = await new ClaudeAdapter(async () => {}).createSession(sessionConfig).then(
+            () => undefined,
+            (err: unknown) => err,
+          );
+
+          expect((error as Error).name).toBe("ClaudeSettingsConfigError");
+          expect((error as Error).message).toContain("inline JSON is not valid JSON");
+          expect((error as Error).message).not.toContain(sentinel);
+          expect(await Bun.file(`${stateFile}.spawns`).exists()).toBeFalse();
+        }
+      } finally {
+        logSpy.mockRestore();
+        warnSpy.mockRestore();
+        errorSpy.mockRestore();
+      }
+      expect(logged.filter((line) => line.includes(sentinel))).toEqual([]);
     },
     { timeout: CHILD_PROCESS_TEST_BUDGET_MS },
   );

package/src/tests/claude-sdk-process.fixture.ts

@@ -1,9 +1,16 @@
+import { appendFileSync } from "node:fs";
 import { rename } from "node:fs/promises";
 
 const mode = process.env.CLAUDE_SDK_FIXTURE_MODE;
 const stateFile = process.env.CLAUDE_SDK_FIXTURE_STATE_FILE;
 const sessionId = "11111111-1111-4111-8111-111111111111";
 
+// Record every invocation, the `--version` probe included, before any exit, so
+// a test can assert that no Claude child started at all.
+if (stateFile) {
+  appendFileSync(`${stateFile}.spawns`, `${JSON.stringify(process.argv.slice(2))}\n`);
+}
+
 if (process.argv.includes("--version")) {
   if (process.env.CLAUDE_SDK_FIXTURE_UNKNOWN_VERSION === "1") process.exit(1);
   console.log("2.1.263 (Claude Code)");