fix(server): resolve Claude SDK executable path on Windows npm installs

apps/server/src/provider/Drivers/ClaudeExecutable.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Effect from "effect/Effect";
+
+import { ClaudeExecutableFileCheck, resolveClaudeSdkExecutablePath } from "./ClaudeExecutable.ts";
+
+const NPM_DIR = "C:\\Users\\dev\\AppData\\Roaming\\npm";
+const NPM_SHIM = `${NPM_DIR}\\claude.cmd`;
+const NPM_PACKAGE_EXE = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+const NPM_PACKAGE_CLI = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`;
+
+function withWindowsResolution(input: {
+ readonly resolvedCommand: string | undefined;
+ readonly existingFiles?: ReadonlyArray<string>;
+}) {
+ const existing = new Set(input.existingFiles ?? []);
+ return <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+ effect.pipe(
+ Effect.provideService(HostProcessPlatform, "win32"),
+ Effect.provideService(SpawnExecutableResolution, () => input.resolvedCommand),
+ Effect.provideService(ClaudeExecutableFileCheck, (filePath) => existing.has(filePath)),
+ );
+}
+
+describe("resolveClaudeSdkExecutablePath", () => {
+ it.effect("returns the configured path unchanged on non-Windows platforms", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ Effect.provideService(HostProcessPlatform, "darwin"),
+ Effect.provideService(SpawnExecutableResolution, () => {
+ throw new Error("must not resolve on non-Windows platforms");
+ }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the resolved absolute path for native Windows executables", () =>
+ Effect.gen(function* () {
+ const nativeBinary = "C:\\Users\\dev\\.local\\bin\\claude.exe";
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: nativeBinary }),
+ ),
+ ).toBe(nativeBinary);
+ }),
+ );
+
+ it.effect("follows an npm launcher shim to the packaged native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_EXE, NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("follows .bat and .ps1 launcher shims the same way", () =>
+ Effect.gen(function* () {
+ for (const shim of [`${NPM_DIR}\\claude.bat`, `${NPM_DIR}\\claude.ps1`]) {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: shim,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }
+ }),
+ );
+
+ it.effect("normalizes mixed-case shim extensions before matching", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: `${NPM_DIR}\\claude.CMD`,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("falls back to cli.js when the package ships no native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_CLI);
+ }),
+ );
+
+ it.effect("returns the configured path when a shim has no known package entry", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: NPM_SHIM }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the configured path when command resolution finds nothing", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: undefined }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+});

apps/server/src/provider/Drivers/ClaudeExecutable.ts

@@ -0,0 +1,90 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * Windows launcher-script extensions that Node cannot spawn without a shell
+ * (`spawn EINVAL` since Node 20.12) and that the Claude Agent SDK therefore
+ * cannot use as `pathToClaudeCodeExecutable`.
+ */
+const WINDOWS_SHIM_EXTENSIONS: ReadonlySet<string> = new Set([".cmd", ".bat", ".ps1"]);
+
+/**
+ * Entry points of the npm `@anthropic-ai/claude-code` package relative to the
+ * global `node_modules` directory that sits next to the npm launcher shim.
+ * Newer package versions ship a native `bin/claude.exe`; older versions only
+ * ship `cli.js`, which the SDK runs with a JavaScript runtime.
+ */
+const NPM_PACKAGE_ENTRY_CANDIDATES = [
+ ["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"],
+ ["node_modules", "@anthropic-ai", "claude-code", "cli.js"],
+] as const;
+
+export type ExecutableFileCheck = (filePath: string) => boolean;
+
+function isExistingFile(filePath: string): boolean {
+ try {
+ return NodeFS.statSync(filePath).isFile();
+ } catch {
+ return false;
+ }
+}
+
+/** Injectable file-existence check so tests can run against a fake filesystem. */
+export const ClaudeExecutableFileCheck = Context.Reference<ExecutableFileCheck>(
+ "server/provider/Drivers/ClaudeExecutableFileCheck",
+ {
+ defaultValue: () => isExistingFile,
+ },
+);
+
+/**
+ * Resolves the configured Claude binary path into a value the Claude Agent
+ * SDK can spawn directly via `pathToClaudeCodeExecutable`.
+ *
+ * The SDK spawns the given path without a shell and without Windows PATH /
+ * PATHEXT resolution, so a bare command name like `claude` fails with
+ * "native binary not found" and an npm `claude.cmd` shim fails with
+ * `spawn EINVAL`. CLI probes avoid this via `resolveSpawnCommand`, which can
+ * fall back to `shell: true`; the SDK offers no such escape hatch.
+ *
+ * On Windows this resolves the command against PATH/PATHEXT and, when the
+ * result is an npm launcher shim, follows it to the real package entry
+ * (`bin/claude.exe`, or `cli.js` for older package versions). On other
+ * platforms the configured value is returned unchanged.
+ */
+export const resolveClaudeSdkExecutablePath = Effect.fn("resolveClaudeSdkExecutablePath")(
+ function* (binaryPath: string, environment: NodeJS.ProcessEnv): Effect.fn.Return<string> {
+ const platform = yield* HostProcessPlatform;
+ if (platform !== "win32") {
+ return binaryPath;
+ }
+
+ const resolveExecutable = yield* SpawnExecutableResolution;
+ const isFile = yield* ClaudeExecutableFileCheck;
+ const resolved = resolveExecutable(binaryPath, platform, environment) ?? binaryPath;
+ const extension = NodePath.win32.extname(resolved).toLowerCase();
+ if (!WINDOWS_SHIM_EXTENSIONS.has(extension)) {
+ return resolved;
+ }
+
+ const shimDirectory = NodePath.win32.dirname(resolved);
+ for (const entrySegments of NPM_PACKAGE_ENTRY_CANDIDATES) {
+ const candidate = NodePath.win32.join(shimDirectory, ...entrySegments);
+ if (isFile(candidate)) {
+ return candidate;
+ }
+ }
+
+ yield* Effect.logWarning(
+ "Claude launcher shim resolved but no known package entry was found next to it; the Claude Agent SDK cannot spawn launcher scripts directly.",
+ { binaryPath, resolvedShimPath: resolved },
+ );
+ return binaryPath;
+ },
+);

apps/server/src/provider/Layers/ClaudeAdapter.ts

@@ -70,6 +70,7 @@ import * as Stream from "effect/Stream";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
  getClaudeModelCapabilities,
@@ -1347,6 +1348,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
  Effect.provideService(Path.Path, path),
  );
+ const claudeSdkExecutablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  const nativeEventLogger =
  options?.nativeEventLogger ??
  (options?.nativeEventLogPath !== undefined
@@ -3405,7 +3410,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
  runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
- const claudeBinaryPath = claudeSettings.binaryPath;
+ const claudeBinaryPath = claudeSdkExecutablePath;
  const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
  const modelSelection =
  input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;

apps/server/src/provider/Layers/ClaudeProvider.ts

@@ -37,6 +37,7 @@ import {
  spawnAndCollect,
  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -588,6 +589,10 @@ const probeClaudeCapabilities = (
  const abort = new AbortController();
  return Effect.gen(function* () {
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+ const executablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  return yield* Effect.tryPromise(async () => {
  const q = claudeQuery({
  // Never yield — we only need initialization data, not a conversation.
@@ -598,7 +603,7 @@ const probeClaudeCapabilities = (
  })(),
  options: {
  persistSession: false,
- pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+ pathToClaudeCodeExecutable: executablePath,
  abortController: abort,
  settingSources: ["user", "project", "local"],
  allowedTools: [],

apps/server/src/provider/Drivers/ClaudeExecutable.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Effect from "effect/Effect";
+
+import { ClaudeExecutableFileCheck, resolveClaudeSdkExecutablePath } from "./ClaudeExecutable.ts";
+
+const NPM_DIR = "C:\\Users\\dev\\AppData\\Roaming\\npm";
+const NPM_SHIM = `${NPM_DIR}\\claude.cmd`;
+const NPM_PACKAGE_EXE = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+const NPM_PACKAGE_CLI = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`;
+
+function withWindowsResolution(input: {
+ readonly resolvedCommand: string | undefined;
+ readonly existingFiles?: ReadonlyArray<string>;
+}) {
+ const existing = new Set(input.existingFiles ?? []);
+ return <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+ effect.pipe(
+ Effect.provideService(HostProcessPlatform, "win32"),
+ Effect.provideService(SpawnExecutableResolution, () => input.resolvedCommand),
+ Effect.provideService(ClaudeExecutableFileCheck, (filePath) => existing.has(filePath)),
+ );
+}
+
+describe("resolveClaudeSdkExecutablePath", () => {
+ it.effect("returns the configured path unchanged on non-Windows platforms", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ Effect.provideService(HostProcessPlatform, "darwin"),
+ Effect.provideService(SpawnExecutableResolution, () => {
+ throw new Error("must not resolve on non-Windows platforms");
+ }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the resolved absolute path for native Windows executables", () =>
+ Effect.gen(function* () {
+ const nativeBinary = "C:\\Users\\dev\\.local\\bin\\claude.exe";
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: nativeBinary }),
+ ),
+ ).toBe(nativeBinary);
+ }),
+ );
+
+ it.effect("follows an npm launcher shim to the packaged native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_EXE, NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("follows .bat and .ps1 launcher shims the same way", () =>
+ Effect.gen(function* () {
+ for (const shim of [`${NPM_DIR}\\claude.bat`, `${NPM_DIR}\\claude.ps1`]) {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: shim,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }
+ }),
+ );
+
+ it.effect("normalizes mixed-case shim extensions before matching", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: `${NPM_DIR}\\claude.CMD`,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("falls back to cli.js when the package ships no native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_CLI);
+ }),
+ );
+
+ it.effect("returns the configured path when a shim has no known package entry", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: NPM_SHIM }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the configured path when command resolution finds nothing", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: undefined }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+});

apps/server/src/provider/Drivers/ClaudeExecutable.ts

@@ -0,0 +1,90 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * Windows launcher-script extensions that Node cannot spawn without a shell
+ * (`spawn EINVAL` since Node 20.12) and that the Claude Agent SDK therefore
+ * cannot use as `pathToClaudeCodeExecutable`.
+ */
+const WINDOWS_SHIM_EXTENSIONS: ReadonlySet<string> = new Set([".cmd", ".bat", ".ps1"]);
+
+/**
+ * Entry points of the npm `@anthropic-ai/claude-code` package relative to the
+ * global `node_modules` directory that sits next to the npm launcher shim.
+ * Newer package versions ship a native `bin/claude.exe`; older versions only
+ * ship `cli.js`, which the SDK runs with a JavaScript runtime.
+ */
+const NPM_PACKAGE_ENTRY_CANDIDATES = [
+ ["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"],
+ ["node_modules", "@anthropic-ai", "claude-code", "cli.js"],
+] as const;
+
+export type ExecutableFileCheck = (filePath: string) => boolean;
+
+function isExistingFile(filePath: string): boolean {
+ try {
+ return NodeFS.statSync(filePath).isFile();
+ } catch {
+ return false;
+ }
+}
+
+/** Injectable file-existence check so tests can run against a fake filesystem. */
+export const ClaudeExecutableFileCheck = Context.Reference<ExecutableFileCheck>(
+ "server/provider/Drivers/ClaudeExecutableFileCheck",
+ {
+ defaultValue: () => isExistingFile,
+ },
+);
+
+/**
+ * Resolves the configured Claude binary path into a value the Claude Agent
+ * SDK can spawn directly via `pathToClaudeCodeExecutable`.
+ *
+ * The SDK spawns the given path without a shell and without Windows PATH /
+ * PATHEXT resolution, so a bare command name like `claude` fails with
+ * "native binary not found" and an npm `claude.cmd` shim fails with
+ * `spawn EINVAL`. CLI probes avoid this via `resolveSpawnCommand`, which can
+ * fall back to `shell: true`; the SDK offers no such escape hatch.
+ *
+ * On Windows this resolves the command against PATH/PATHEXT and, when the
+ * result is an npm launcher shim, follows it to the real package entry
+ * (`bin/claude.exe`, or `cli.js` for older package versions). On other
+ * platforms the configured value is returned unchanged.
+ */
+export const resolveClaudeSdkExecutablePath = Effect.fn("resolveClaudeSdkExecutablePath")(
+ function* (binaryPath: string, environment: NodeJS.ProcessEnv): Effect.fn.Return<string> {
+ const platform = yield* HostProcessPlatform;
+ if (platform !== "win32") {
+ return binaryPath;
+ }
+
+ const resolveExecutable = yield* SpawnExecutableResolution;
+ const isFile = yield* ClaudeExecutableFileCheck;
+ const resolved = resolveExecutable(binaryPath, platform, environment) ?? binaryPath;
+ const extension = NodePath.win32.extname(resolved).toLowerCase();
+ if (!WINDOWS_SHIM_EXTENSIONS.has(extension)) {
+ return resolved;
+ }
+
+ const shimDirectory = NodePath.win32.dirname(resolved);
+ for (const entrySegments of NPM_PACKAGE_ENTRY_CANDIDATES) {
+ const candidate = NodePath.win32.join(shimDirectory, ...entrySegments);
+ if (isFile(candidate)) {
+ return candidate;
+ }
+ }
+
+ yield* Effect.logWarning(
+ "Claude launcher shim resolved but no known package entry was found next to it; the Claude Agent SDK cannot spawn launcher scripts directly.",
+ { binaryPath, resolvedShimPath: resolved },
+ );
+ return binaryPath;
+ },
+);

apps/server/src/provider/Layers/ClaudeAdapter.ts

@@ -70,6 +70,7 @@ import * as Stream from "effect/Stream";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
  getClaudeModelCapabilities,
@@ -1347,6 +1348,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
  Effect.provideService(Path.Path, path),
  );
+ const claudeSdkExecutablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  const nativeEventLogger =
  options?.nativeEventLogger ??
  (options?.nativeEventLogPath !== undefined
@@ -3405,7 +3410,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
  runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
- const claudeBinaryPath = claudeSettings.binaryPath;
+ const claudeBinaryPath = claudeSdkExecutablePath;
  const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
  const modelSelection =
  input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;

apps/server/src/provider/Layers/ClaudeProvider.ts

@@ -37,6 +37,7 @@ import {
  spawnAndCollect,
  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -588,6 +589,10 @@ const probeClaudeCapabilities = (
  const abort = new AbortController();
  return Effect.gen(function* () {
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+ const executablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  return yield* Effect.tryPromise(async () => {
  const q = claudeQuery({
  // Never yield — we only need initialization data, not a conversation.
@@ -598,7 +603,7 @@ const probeClaudeCapabilities = (
  })(),
  options: {
  persistSession: false,
- pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+ pathToClaudeCodeExecutable: executablePath,
  abortController: abort,
  settingSources: ["user", "project", "local"],
  allowedTools: [],

apps/server/src/provider/Drivers/ClaudeExecutable.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Effect from "effect/Effect";
+
+import { ClaudeExecutableFileCheck, resolveClaudeSdkExecutablePath } from "./ClaudeExecutable.ts";
+
+const NPM_DIR = "C:\\Users\\dev\\AppData\\Roaming\\npm";
+const NPM_SHIM = `${NPM_DIR}\\claude.cmd`;
+const NPM_PACKAGE_EXE = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+const NPM_PACKAGE_CLI = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`;
+
+function withWindowsResolution(input: {
+ readonly resolvedCommand: string | undefined;
+ readonly existingFiles?: ReadonlyArray<string>;
+}) {
+ const existing = new Set(input.existingFiles ?? []);
+ return <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+ effect.pipe(
+ Effect.provideService(HostProcessPlatform, "win32"),
+ Effect.provideService(SpawnExecutableResolution, () => input.resolvedCommand),
+ Effect.provideService(ClaudeExecutableFileCheck, (filePath) => existing.has(filePath)),
+ );
+}
+
+describe("resolveClaudeSdkExecutablePath", () => {
+ it.effect("returns the configured path unchanged on non-Windows platforms", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ Effect.provideService(HostProcessPlatform, "darwin"),
+ Effect.provideService(SpawnExecutableResolution, () => {
+ throw new Error("must not resolve on non-Windows platforms");
+ }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the resolved absolute path for native Windows executables", () =>
+ Effect.gen(function* () {
+ const nativeBinary = "C:\\Users\\dev\\.local\\bin\\claude.exe";
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: nativeBinary }),
+ ),
+ ).toBe(nativeBinary);
+ }),
+ );
+
+ it.effect("follows an npm launcher shim to the packaged native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_EXE, NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("follows .bat and .ps1 launcher shims the same way", () =>
+ Effect.gen(function* () {
+ for (const shim of [`${NPM_DIR}\\claude.bat`, `${NPM_DIR}\\claude.ps1`]) {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: shim,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }
+ }),
+ );
+
+ it.effect("normalizes mixed-case shim extensions before matching", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: `${NPM_DIR}\\claude.CMD`,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("falls back to cli.js when the package ships no native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_CLI);
+ }),
+ );
+
+ it.effect("returns the configured path when a shim has no known package entry", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: NPM_SHIM }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the configured path when command resolution finds nothing", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: undefined }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+});

apps/server/src/provider/Drivers/ClaudeExecutable.ts

@@ -0,0 +1,90 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * Windows launcher-script extensions that Node cannot spawn without a shell
+ * (`spawn EINVAL` since Node 20.12) and that the Claude Agent SDK therefore
+ * cannot use as `pathToClaudeCodeExecutable`.
+ */
+const WINDOWS_SHIM_EXTENSIONS: ReadonlySet<string> = new Set([".cmd", ".bat", ".ps1"]);
+
+/**
+ * Entry points of the npm `@anthropic-ai/claude-code` package relative to the
+ * global `node_modules` directory that sits next to the npm launcher shim.
+ * Newer package versions ship a native `bin/claude.exe`; older versions only
+ * ship `cli.js`, which the SDK runs with a JavaScript runtime.
+ */
+const NPM_PACKAGE_ENTRY_CANDIDATES = [
+ ["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"],
+ ["node_modules", "@anthropic-ai", "claude-code", "cli.js"],
+] as const;
+
+export type ExecutableFileCheck = (filePath: string) => boolean;
+
+function isExistingFile(filePath: string): boolean {
+ try {
+ return NodeFS.statSync(filePath).isFile();
+ } catch {
+ return false;
+ }
+}
+
+/** Injectable file-existence check so tests can run against a fake filesystem. */
+export const ClaudeExecutableFileCheck = Context.Reference<ExecutableFileCheck>(
+ "server/provider/Drivers/ClaudeExecutableFileCheck",
+ {
+ defaultValue: () => isExistingFile,
+ },
+);
+
+/**
+ * Resolves the configured Claude binary path into a value the Claude Agent
+ * SDK can spawn directly via `pathToClaudeCodeExecutable`.
+ *
+ * The SDK spawns the given path without a shell and without Windows PATH /
+ * PATHEXT resolution, so a bare command name like `claude` fails with
+ * "native binary not found" and an npm `claude.cmd` shim fails with
+ * `spawn EINVAL`. CLI probes avoid this via `resolveSpawnCommand`, which can
+ * fall back to `shell: true`; the SDK offers no such escape hatch.
+ *
+ * On Windows this resolves the command against PATH/PATHEXT and, when the
+ * result is an npm launcher shim, follows it to the real package entry
+ * (`bin/claude.exe`, or `cli.js` for older package versions). On other
+ * platforms the configured value is returned unchanged.
+ */
+export const resolveClaudeSdkExecutablePath = Effect.fn("resolveClaudeSdkExecutablePath")(
+ function* (binaryPath: string, environment: NodeJS.ProcessEnv): Effect.fn.Return<string> {
+ const platform = yield* HostProcessPlatform;
+ if (platform !== "win32") {
+ return binaryPath;
+ }
+
+ const resolveExecutable = yield* SpawnExecutableResolution;
+ const isFile = yield* ClaudeExecutableFileCheck;
+ const resolved = resolveExecutable(binaryPath, platform, environment) ?? binaryPath;
+ const extension = NodePath.win32.extname(resolved).toLowerCase();
+ if (!WINDOWS_SHIM_EXTENSIONS.has(extension)) {
+ return resolved;
+ }
+
+ const shimDirectory = NodePath.win32.dirname(resolved);
+ for (const entrySegments of NPM_PACKAGE_ENTRY_CANDIDATES) {
+ const candidate = NodePath.win32.join(shimDirectory, ...entrySegments);
+ if (isFile(candidate)) {
+ return candidate;
+ }
+ }
+
+ yield* Effect.logWarning(
+ "Claude launcher shim resolved but no known package entry was found next to it; the Claude Agent SDK cannot spawn launcher scripts directly.",
+ { binaryPath, resolvedShimPath: resolved },
+ );
+ return binaryPath;
+ },
+);

apps/server/src/provider/Layers/ClaudeAdapter.ts

@@ -70,6 +70,7 @@ import * as Stream from "effect/Stream";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
  getClaudeModelCapabilities,
@@ -1347,6 +1348,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
  Effect.provideService(Path.Path, path),
  );
+ const claudeSdkExecutablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  const nativeEventLogger =
  options?.nativeEventLogger ??
  (options?.nativeEventLogPath !== undefined
@@ -3405,7 +3410,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
  runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
- const claudeBinaryPath = claudeSettings.binaryPath;
+ const claudeBinaryPath = claudeSdkExecutablePath;
  const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
  const modelSelection =
  input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;

apps/server/src/provider/Layers/ClaudeProvider.ts

@@ -37,6 +37,7 @@ import {
  spawnAndCollect,
  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -588,6 +589,10 @@ const probeClaudeCapabilities = (
  const abort = new AbortController();
  return Effect.gen(function* () {
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+ const executablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  return yield* Effect.tryPromise(async () => {
  const q = claudeQuery({
  // Never yield — we only need initialization data, not a conversation.
@@ -598,7 +603,7 @@ const probeClaudeCapabilities = (
  })(),
  options: {
  persistSession: false,
- pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+ pathToClaudeCodeExecutable: executablePath,
  abortController: abort,
  settingSources: ["user", "project", "local"],
  allowedTools: [],

apps/server/src/provider/Drivers/ClaudeExecutable.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Effect from "effect/Effect";
+
+import { ClaudeExecutableFileCheck, resolveClaudeSdkExecutablePath } from "./ClaudeExecutable.ts";
+
+const NPM_DIR = "C:\\Users\\dev\\AppData\\Roaming\\npm";
+const NPM_SHIM = `${NPM_DIR}\\claude.cmd`;
+const NPM_PACKAGE_EXE = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+const NPM_PACKAGE_CLI = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`;
+
+function withWindowsResolution(input: {
+ readonly resolvedCommand: string | undefined;
+ readonly existingFiles?: ReadonlyArray<string>;
+}) {
+ const existing = new Set(input.existingFiles ?? []);
+ return <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+ effect.pipe(
+ Effect.provideService(HostProcessPlatform, "win32"),
+ Effect.provideService(SpawnExecutableResolution, () => input.resolvedCommand),
+ Effect.provideService(ClaudeExecutableFileCheck, (filePath) => existing.has(filePath)),
+ );
+}
+
+describe("resolveClaudeSdkExecutablePath", () => {
+ it.effect("returns the configured path unchanged on non-Windows platforms", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ Effect.provideService(HostProcessPlatform, "darwin"),
+ Effect.provideService(SpawnExecutableResolution, () => {
+ throw new Error("must not resolve on non-Windows platforms");
+ }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the resolved absolute path for native Windows executables", () =>
+ Effect.gen(function* () {
+ const nativeBinary = "C:\\Users\\dev\\.local\\bin\\claude.exe";
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: nativeBinary }),
+ ),
+ ).toBe(nativeBinary);
+ }),
+ );
+
+ it.effect("follows an npm launcher shim to the packaged native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_EXE, NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("follows .bat and .ps1 launcher shims the same way", () =>
+ Effect.gen(function* () {
+ for (const shim of [`${NPM_DIR}\\claude.bat`, `${NPM_DIR}\\claude.ps1`]) {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: shim,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }
+ }),
+ );
+
+ it.effect("normalizes mixed-case shim extensions before matching", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: `${NPM_DIR}\\claude.CMD`,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("falls back to cli.js when the package ships no native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_CLI);
+ }),
+ );
+
+ it.effect("returns the configured path when a shim has no known package entry", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: NPM_SHIM }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the configured path when command resolution finds nothing", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: undefined }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+});

apps/server/src/provider/Drivers/ClaudeExecutable.ts

@@ -0,0 +1,90 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * Windows launcher-script extensions that Node cannot spawn without a shell
+ * (`spawn EINVAL` since Node 20.12) and that the Claude Agent SDK therefore
+ * cannot use as `pathToClaudeCodeExecutable`.
+ */
+const WINDOWS_SHIM_EXTENSIONS: ReadonlySet<string> = new Set([".cmd", ".bat", ".ps1"]);
+
+/**
+ * Entry points of the npm `@anthropic-ai/claude-code` package relative to the
+ * global `node_modules` directory that sits next to the npm launcher shim.
+ * Newer package versions ship a native `bin/claude.exe`; older versions only
+ * ship `cli.js`, which the SDK runs with a JavaScript runtime.
+ */
+const NPM_PACKAGE_ENTRY_CANDIDATES = [
+ ["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"],
+ ["node_modules", "@anthropic-ai", "claude-code", "cli.js"],
+] as const;
+
+export type ExecutableFileCheck = (filePath: string) => boolean;
+
+function isExistingFile(filePath: string): boolean {
+ try {
+ return NodeFS.statSync(filePath).isFile();
+ } catch {
+ return false;
+ }
+}
+
+/** Injectable file-existence check so tests can run against a fake filesystem. */
+export const ClaudeExecutableFileCheck = Context.Reference<ExecutableFileCheck>(
+ "server/provider/Drivers/ClaudeExecutableFileCheck",
+ {
+ defaultValue: () => isExistingFile,
+ },
+);
+
+/**
+ * Resolves the configured Claude binary path into a value the Claude Agent
+ * SDK can spawn directly via `pathToClaudeCodeExecutable`.
+ *
+ * The SDK spawns the given path without a shell and without Windows PATH /
+ * PATHEXT resolution, so a bare command name like `claude` fails with
+ * "native binary not found" and an npm `claude.cmd` shim fails with
+ * `spawn EINVAL`. CLI probes avoid this via `resolveSpawnCommand`, which can
+ * fall back to `shell: true`; the SDK offers no such escape hatch.
+ *
+ * On Windows this resolves the command against PATH/PATHEXT and, when the
+ * result is an npm launcher shim, follows it to the real package entry
+ * (`bin/claude.exe`, or `cli.js` for older package versions). On other
+ * platforms the configured value is returned unchanged.
+ */
+export const resolveClaudeSdkExecutablePath = Effect.fn("resolveClaudeSdkExecutablePath")(
+ function* (binaryPath: string, environment: NodeJS.ProcessEnv): Effect.fn.Return<string> {
+ const platform = yield* HostProcessPlatform;
+ if (platform !== "win32") {
+ return binaryPath;
+ }
+
+ const resolveExecutable = yield* SpawnExecutableResolution;
+ const isFile = yield* ClaudeExecutableFileCheck;
+ const resolved = resolveExecutable(binaryPath, platform, environment) ?? binaryPath;
+ const extension = NodePath.win32.extname(resolved).toLowerCase();
+ if (!WINDOWS_SHIM_EXTENSIONS.has(extension)) {
+ return resolved;
+ }
+
+ const shimDirectory = NodePath.win32.dirname(resolved);
+ for (const entrySegments of NPM_PACKAGE_ENTRY_CANDIDATES) {
+ const candidate = NodePath.win32.join(shimDirectory, ...entrySegments);
+ if (isFile(candidate)) {
+ return candidate;
+ }
+ }
+
+ yield* Effect.logWarning(
+ "Claude launcher shim resolved but no known package entry was found next to it; the Claude Agent SDK cannot spawn launcher scripts directly.",
+ { binaryPath, resolvedShimPath: resolved },
+ );
+ return binaryPath;
+ },
+);

apps/server/src/provider/Layers/ClaudeAdapter.ts

@@ -70,6 +70,7 @@ import * as Stream from "effect/Stream";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
  getClaudeModelCapabilities,
@@ -1347,6 +1348,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
  Effect.provideService(Path.Path, path),
  );
+ const claudeSdkExecutablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  const nativeEventLogger =
  options?.nativeEventLogger ??
  (options?.nativeEventLogPath !== undefined
@@ -3405,7 +3410,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
  runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
- const claudeBinaryPath = claudeSettings.binaryPath;
+ const claudeBinaryPath = claudeSdkExecutablePath;
  const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
  const modelSelection =
  input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;

apps/server/src/provider/Layers/ClaudeProvider.ts

@@ -37,6 +37,7 @@ import {
  spawnAndCollect,
  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -588,6 +589,10 @@ const probeClaudeCapabilities = (
  const abort = new AbortController();
  return Effect.gen(function* () {
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+ const executablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  return yield* Effect.tryPromise(async () => {
  const q = claudeQuery({
  // Never yield — we only need initialization data, not a conversation.
@@ -598,7 +603,7 @@ const probeClaudeCapabilities = (
  })(),
  options: {
  persistSession: false,
- pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+ pathToClaudeCodeExecutable: executablePath,
  abortController: abort,
  settingSources: ["user", "project", "local"],
  allowedTools: [],

apps/server/src/provider/Drivers/ClaudeExecutable.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Effect from "effect/Effect";
+
+import { ClaudeExecutableFileCheck, resolveClaudeSdkExecutablePath } from "./ClaudeExecutable.ts";
+
+const NPM_DIR = "C:\\Users\\dev\\AppData\\Roaming\\npm";
+const NPM_SHIM = `${NPM_DIR}\\claude.cmd`;
+const NPM_PACKAGE_EXE = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+const NPM_PACKAGE_CLI = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`;
+
+function withWindowsResolution(input: {
+ readonly resolvedCommand: string | undefined;
+ readonly existingFiles?: ReadonlyArray<string>;
+}) {
+ const existing = new Set(input.existingFiles ?? []);
+ return <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+ effect.pipe(
+ Effect.provideService(HostProcessPlatform, "win32"),
+ Effect.provideService(SpawnExecutableResolution, () => input.resolvedCommand),
+ Effect.provideService(ClaudeExecutableFileCheck, (filePath) => existing.has(filePath)),
+ );
+}
+
+describe("resolveClaudeSdkExecutablePath", () => {
+ it.effect("returns the configured path unchanged on non-Windows platforms", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ Effect.provideService(HostProcessPlatform, "darwin"),
+ Effect.provideService(SpawnExecutableResolution, () => {
+ throw new Error("must not resolve on non-Windows platforms");
+ }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the resolved absolute path for native Windows executables", () =>
+ Effect.gen(function* () {
+ const nativeBinary = "C:\\Users\\dev\\.local\\bin\\claude.exe";
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: nativeBinary }),
+ ),
+ ).toBe(nativeBinary);
+ }),
+ );
+
+ it.effect("follows an npm launcher shim to the packaged native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_EXE, NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("follows .bat and .ps1 launcher shims the same way", () =>
+ Effect.gen(function* () {
+ for (const shim of [`${NPM_DIR}\\claude.bat`, `${NPM_DIR}\\claude.ps1`]) {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: shim,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }
+ }),
+ );
+
+ it.effect("normalizes mixed-case shim extensions before matching", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: `${NPM_DIR}\\claude.CMD`,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("falls back to cli.js when the package ships no native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_CLI);
+ }),
+ );
+
+ it.effect("returns the configured path when a shim has no known package entry", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: NPM_SHIM }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the configured path when command resolution finds nothing", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: undefined }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+});

apps/server/src/provider/Drivers/ClaudeExecutable.ts

@@ -0,0 +1,90 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * Windows launcher-script extensions that Node cannot spawn without a shell
+ * (`spawn EINVAL` since Node 20.12) and that the Claude Agent SDK therefore
+ * cannot use as `pathToClaudeCodeExecutable`.
+ */
+const WINDOWS_SHIM_EXTENSIONS: ReadonlySet<string> = new Set([".cmd", ".bat", ".ps1"]);
+
+/**
+ * Entry points of the npm `@anthropic-ai/claude-code` package relative to the
+ * global `node_modules` directory that sits next to the npm launcher shim.
+ * Newer package versions ship a native `bin/claude.exe`; older versions only
+ * ship `cli.js`, which the SDK runs with a JavaScript runtime.
+ */
+const NPM_PACKAGE_ENTRY_CANDIDATES = [
+ ["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"],
+ ["node_modules", "@anthropic-ai", "claude-code", "cli.js"],
+] as const;
+
+export type ExecutableFileCheck = (filePath: string) => boolean;
+
+function isExistingFile(filePath: string): boolean {
+ try {
+ return NodeFS.statSync(filePath).isFile();
+ } catch {
+ return false;
+ }
+}
+
+/** Injectable file-existence check so tests can run against a fake filesystem. */
+export const ClaudeExecutableFileCheck = Context.Reference<ExecutableFileCheck>(
+ "server/provider/Drivers/ClaudeExecutableFileCheck",
+ {
+ defaultValue: () => isExistingFile,
+ },
+);
+
+/**
+ * Resolves the configured Claude binary path into a value the Claude Agent
+ * SDK can spawn directly via `pathToClaudeCodeExecutable`.
+ *
+ * The SDK spawns the given path without a shell and without Windows PATH /
+ * PATHEXT resolution, so a bare command name like `claude` fails with
+ * "native binary not found" and an npm `claude.cmd` shim fails with
+ * `spawn EINVAL`. CLI probes avoid this via `resolveSpawnCommand`, which can
+ * fall back to `shell: true`; the SDK offers no such escape hatch.
+ *
+ * On Windows this resolves the command against PATH/PATHEXT and, when the
+ * result is an npm launcher shim, follows it to the real package entry
+ * (`bin/claude.exe`, or `cli.js` for older package versions). On other
+ * platforms the configured value is returned unchanged.
+ */
+export const resolveClaudeSdkExecutablePath = Effect.fn("resolveClaudeSdkExecutablePath")(
+ function* (binaryPath: string, environment: NodeJS.ProcessEnv): Effect.fn.Return<string> {
+ const platform = yield* HostProcessPlatform;
+ if (platform !== "win32") {
+ return binaryPath;
+ }
+
+ const resolveExecutable = yield* SpawnExecutableResolution;
+ const isFile = yield* ClaudeExecutableFileCheck;
+ const resolved = resolveExecutable(binaryPath, platform, environment) ?? binaryPath;
+ const extension = NodePath.win32.extname(resolved).toLowerCase();
+ if (!WINDOWS_SHIM_EXTENSIONS.has(extension)) {
+ return resolved;
+ }
+
+ const shimDirectory = NodePath.win32.dirname(resolved);
+ for (const entrySegments of NPM_PACKAGE_ENTRY_CANDIDATES) {
+ const candidate = NodePath.win32.join(shimDirectory, ...entrySegments);
+ if (isFile(candidate)) {
+ return candidate;
+ }
+ }
+
+ yield* Effect.logWarning(
+ "Claude launcher shim resolved but no known package entry was found next to it; the Claude Agent SDK cannot spawn launcher scripts directly.",
+ { binaryPath, resolvedShimPath: resolved },
+ );
+ return binaryPath;
+ },
+);

apps/server/src/provider/Layers/ClaudeAdapter.ts

@@ -70,6 +70,7 @@ import * as Stream from "effect/Stream";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
  getClaudeModelCapabilities,
@@ -1347,6 +1348,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
  Effect.provideService(Path.Path, path),
  );
+ const claudeSdkExecutablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  const nativeEventLogger =
  options?.nativeEventLogger ??
  (options?.nativeEventLogPath !== undefined
@@ -3405,7 +3410,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
  runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
- const claudeBinaryPath = claudeSettings.binaryPath;
+ const claudeBinaryPath = claudeSdkExecutablePath;
  const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
  const modelSelection =
  input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;

apps/server/src/provider/Layers/ClaudeProvider.ts

@@ -37,6 +37,7 @@ import {
  spawnAndCollect,
  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -588,6 +589,10 @@ const probeClaudeCapabilities = (
  const abort = new AbortController();
  return Effect.gen(function* () {
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+ const executablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  return yield* Effect.tryPromise(async () => {
  const q = claudeQuery({
  // Never yield — we only need initialization data, not a conversation.
@@ -598,7 +603,7 @@ const probeClaudeCapabilities = (
  })(),
  options: {
  persistSession: false,
- pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+ pathToClaudeCodeExecutable: executablePath,
  abortController: abort,
  settingSources: ["user", "project", "local"],
  allowedTools: [],

apps/server/src/provider/Drivers/ClaudeExecutable.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Effect from "effect/Effect";
+
+import { ClaudeExecutableFileCheck, resolveClaudeSdkExecutablePath } from "./ClaudeExecutable.ts";
+
+const NPM_DIR = "C:\\Users\\dev\\AppData\\Roaming\\npm";
+const NPM_SHIM = `${NPM_DIR}\\claude.cmd`;
+const NPM_PACKAGE_EXE = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+const NPM_PACKAGE_CLI = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`;
+
+function withWindowsResolution(input: {
+ readonly resolvedCommand: string | undefined;
+ readonly existingFiles?: ReadonlyArray<string>;
+}) {
+ const existing = new Set(input.existingFiles ?? []);
+ return <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+ effect.pipe(
+ Effect.provideService(HostProcessPlatform, "win32"),
+ Effect.provideService(SpawnExecutableResolution, () => input.resolvedCommand),
+ Effect.provideService(ClaudeExecutableFileCheck, (filePath) => existing.has(filePath)),
+ );
+}
+
+describe("resolveClaudeSdkExecutablePath", () => {
+ it.effect("returns the configured path unchanged on non-Windows platforms", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ Effect.provideService(HostProcessPlatform, "darwin"),
+ Effect.provideService(SpawnExecutableResolution, () => {
+ throw new Error("must not resolve on non-Windows platforms");
+ }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the resolved absolute path for native Windows executables", () =>
+ Effect.gen(function* () {
+ const nativeBinary = "C:\\Users\\dev\\.local\\bin\\claude.exe";
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: nativeBinary }),
+ ),
+ ).toBe(nativeBinary);
+ }),
+ );
+
+ it.effect("follows an npm launcher shim to the packaged native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_EXE, NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("follows .bat and .ps1 launcher shims the same way", () =>
+ Effect.gen(function* () {
+ for (const shim of [`${NPM_DIR}\\claude.bat`, `${NPM_DIR}\\claude.ps1`]) {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: shim,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }
+ }),
+ );
+
+ it.effect("normalizes mixed-case shim extensions before matching", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: `${NPM_DIR}\\claude.CMD`,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("falls back to cli.js when the package ships no native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_CLI);
+ }),
+ );
+
+ it.effect("returns the configured path when a shim has no known package entry", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: NPM_SHIM }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the configured path when command resolution finds nothing", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: undefined }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+});

apps/server/src/provider/Drivers/ClaudeExecutable.ts

@@ -0,0 +1,90 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * Windows launcher-script extensions that Node cannot spawn without a shell
+ * (`spawn EINVAL` since Node 20.12) and that the Claude Agent SDK therefore
+ * cannot use as `pathToClaudeCodeExecutable`.
+ */
+const WINDOWS_SHIM_EXTENSIONS: ReadonlySet<string> = new Set([".cmd", ".bat", ".ps1"]);
+
+/**
+ * Entry points of the npm `@anthropic-ai/claude-code` package relative to the
+ * global `node_modules` directory that sits next to the npm launcher shim.
+ * Newer package versions ship a native `bin/claude.exe`; older versions only
+ * ship `cli.js`, which the SDK runs with a JavaScript runtime.
+ */
+const NPM_PACKAGE_ENTRY_CANDIDATES = [
+ ["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"],
+ ["node_modules", "@anthropic-ai", "claude-code", "cli.js"],
+] as const;
+
+export type ExecutableFileCheck = (filePath: string) => boolean;
+
+function isExistingFile(filePath: string): boolean {
+ try {
+ return NodeFS.statSync(filePath).isFile();
+ } catch {
+ return false;
+ }
+}
+
+/** Injectable file-existence check so tests can run against a fake filesystem. */
+export const ClaudeExecutableFileCheck = Context.Reference<ExecutableFileCheck>(
+ "server/provider/Drivers/ClaudeExecutableFileCheck",
+ {
+ defaultValue: () => isExistingFile,
+ },
+);
+
+/**
+ * Resolves the configured Claude binary path into a value the Claude Agent
+ * SDK can spawn directly via `pathToClaudeCodeExecutable`.
+ *
+ * The SDK spawns the given path without a shell and without Windows PATH /
+ * PATHEXT resolution, so a bare command name like `claude` fails with
+ * "native binary not found" and an npm `claude.cmd` shim fails with
+ * `spawn EINVAL`. CLI probes avoid this via `resolveSpawnCommand`, which can
+ * fall back to `shell: true`; the SDK offers no such escape hatch.
+ *
+ * On Windows this resolves the command against PATH/PATHEXT and, when the
+ * result is an npm launcher shim, follows it to the real package entry
+ * (`bin/claude.exe`, or `cli.js` for older package versions). On other
+ * platforms the configured value is returned unchanged.
+ */
+export const resolveClaudeSdkExecutablePath = Effect.fn("resolveClaudeSdkExecutablePath")(
+ function* (binaryPath: string, environment: NodeJS.ProcessEnv): Effect.fn.Return<string> {
+ const platform = yield* HostProcessPlatform;
+ if (platform !== "win32") {
+ return binaryPath;
+ }
+
+ const resolveExecutable = yield* SpawnExecutableResolution;
+ const isFile = yield* ClaudeExecutableFileCheck;
+ const resolved = resolveExecutable(binaryPath, platform, environment) ?? binaryPath;
+ const extension = NodePath.win32.extname(resolved).toLowerCase();
+ if (!WINDOWS_SHIM_EXTENSIONS.has(extension)) {
+ return resolved;
+ }
+
+ const shimDirectory = NodePath.win32.dirname(resolved);
+ for (const entrySegments of NPM_PACKAGE_ENTRY_CANDIDATES) {
+ const candidate = NodePath.win32.join(shimDirectory, ...entrySegments);
+ if (isFile(candidate)) {
+ return candidate;
+ }
+ }
+
+ yield* Effect.logWarning(
+ "Claude launcher shim resolved but no known package entry was found next to it; the Claude Agent SDK cannot spawn launcher scripts directly.",
+ { binaryPath, resolvedShimPath: resolved },
+ );
+ return binaryPath;
+ },
+);

apps/server/src/provider/Layers/ClaudeAdapter.ts

@@ -70,6 +70,7 @@ import * as Stream from "effect/Stream";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
  getClaudeModelCapabilities,
@@ -1347,6 +1348,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
  Effect.provideService(Path.Path, path),
  );
+ const claudeSdkExecutablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  const nativeEventLogger =
  options?.nativeEventLogger ??
  (options?.nativeEventLogPath !== undefined
@@ -3405,7 +3410,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
  runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
- const claudeBinaryPath = claudeSettings.binaryPath;
+ const claudeBinaryPath = claudeSdkExecutablePath;
  const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
  const modelSelection =
  input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;

apps/server/src/provider/Layers/ClaudeProvider.ts

@@ -37,6 +37,7 @@ import {
  spawnAndCollect,
  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -588,6 +589,10 @@ const probeClaudeCapabilities = (
  const abort = new AbortController();
  return Effect.gen(function* () {
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+ const executablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  return yield* Effect.tryPromise(async () => {
  const q = claudeQuery({
  // Never yield — we only need initialization data, not a conversation.
@@ -598,7 +603,7 @@ const probeClaudeCapabilities = (
  })(),
  options: {
  persistSession: false,
- pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+ pathToClaudeCodeExecutable: executablePath,
  abortController: abort,
  settingSources: ["user", "project", "local"],
  allowedTools: [],

apps/server/src/provider/Drivers/ClaudeExecutable.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Effect from "effect/Effect";
+
+import { ClaudeExecutableFileCheck, resolveClaudeSdkExecutablePath } from "./ClaudeExecutable.ts";
+
+const NPM_DIR = "C:\\Users\\dev\\AppData\\Roaming\\npm";
+const NPM_SHIM = `${NPM_DIR}\\claude.cmd`;
+const NPM_PACKAGE_EXE = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+const NPM_PACKAGE_CLI = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`;
+
+function withWindowsResolution(input: {
+ readonly resolvedCommand: string | undefined;
+ readonly existingFiles?: ReadonlyArray<string>;
+}) {
+ const existing = new Set(input.existingFiles ?? []);
+ return <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+ effect.pipe(
+ Effect.provideService(HostProcessPlatform, "win32"),
+ Effect.provideService(SpawnExecutableResolution, () => input.resolvedCommand),
+ Effect.provideService(ClaudeExecutableFileCheck, (filePath) => existing.has(filePath)),
+ );
+}
+
+describe("resolveClaudeSdkExecutablePath", () => {
+ it.effect("returns the configured path unchanged on non-Windows platforms", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ Effect.provideService(HostProcessPlatform, "darwin"),
+ Effect.provideService(SpawnExecutableResolution, () => {
+ throw new Error("must not resolve on non-Windows platforms");
+ }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the resolved absolute path for native Windows executables", () =>
+ Effect.gen(function* () {
+ const nativeBinary = "C:\\Users\\dev\\.local\\bin\\claude.exe";
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: nativeBinary }),
+ ),
+ ).toBe(nativeBinary);
+ }),
+ );
+
+ it.effect("follows an npm launcher shim to the packaged native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_EXE, NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("follows .bat and .ps1 launcher shims the same way", () =>
+ Effect.gen(function* () {
+ for (const shim of [`${NPM_DIR}\\claude.bat`, `${NPM_DIR}\\claude.ps1`]) {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: shim,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }
+ }),
+ );
+
+ it.effect("normalizes mixed-case shim extensions before matching", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: `${NPM_DIR}\\claude.CMD`,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("falls back to cli.js when the package ships no native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_CLI);
+ }),
+ );
+
+ it.effect("returns the configured path when a shim has no known package entry", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: NPM_SHIM }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the configured path when command resolution finds nothing", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: undefined }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+});

apps/server/src/provider/Drivers/ClaudeExecutable.ts

@@ -0,0 +1,90 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * Windows launcher-script extensions that Node cannot spawn without a shell
+ * (`spawn EINVAL` since Node 20.12) and that the Claude Agent SDK therefore
+ * cannot use as `pathToClaudeCodeExecutable`.
+ */
+const WINDOWS_SHIM_EXTENSIONS: ReadonlySet<string> = new Set([".cmd", ".bat", ".ps1"]);
+
+/**
+ * Entry points of the npm `@anthropic-ai/claude-code` package relative to the
+ * global `node_modules` directory that sits next to the npm launcher shim.
+ * Newer package versions ship a native `bin/claude.exe`; older versions only
+ * ship `cli.js`, which the SDK runs with a JavaScript runtime.
+ */
+const NPM_PACKAGE_ENTRY_CANDIDATES = [
+ ["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"],
+ ["node_modules", "@anthropic-ai", "claude-code", "cli.js"],
+] as const;
+
+export type ExecutableFileCheck = (filePath: string) => boolean;
+
+function isExistingFile(filePath: string): boolean {
+ try {
+ return NodeFS.statSync(filePath).isFile();
+ } catch {
+ return false;
+ }
+}
+
+/** Injectable file-existence check so tests can run against a fake filesystem. */
+export const ClaudeExecutableFileCheck = Context.Reference<ExecutableFileCheck>(
+ "server/provider/Drivers/ClaudeExecutableFileCheck",
+ {
+ defaultValue: () => isExistingFile,
+ },
+);
+
+/**
+ * Resolves the configured Claude binary path into a value the Claude Agent
+ * SDK can spawn directly via `pathToClaudeCodeExecutable`.
+ *
+ * The SDK spawns the given path without a shell and without Windows PATH /
+ * PATHEXT resolution, so a bare command name like `claude` fails with
+ * "native binary not found" and an npm `claude.cmd` shim fails with
+ * `spawn EINVAL`. CLI probes avoid this via `resolveSpawnCommand`, which can
+ * fall back to `shell: true`; the SDK offers no such escape hatch.
+ *
+ * On Windows this resolves the command against PATH/PATHEXT and, when the
+ * result is an npm launcher shim, follows it to the real package entry
+ * (`bin/claude.exe`, or `cli.js` for older package versions). On other
+ * platforms the configured value is returned unchanged.
+ */
+export const resolveClaudeSdkExecutablePath = Effect.fn("resolveClaudeSdkExecutablePath")(
+ function* (binaryPath: string, environment: NodeJS.ProcessEnv): Effect.fn.Return<string> {
+ const platform = yield* HostProcessPlatform;
+ if (platform !== "win32") {
+ return binaryPath;
+ }
+
+ const resolveExecutable = yield* SpawnExecutableResolution;
+ const isFile = yield* ClaudeExecutableFileCheck;
+ const resolved = resolveExecutable(binaryPath, platform, environment) ?? binaryPath;
+ const extension = NodePath.win32.extname(resolved).toLowerCase();
+ if (!WINDOWS_SHIM_EXTENSIONS.has(extension)) {
+ return resolved;
+ }
+
+ const shimDirectory = NodePath.win32.dirname(resolved);
+ for (const entrySegments of NPM_PACKAGE_ENTRY_CANDIDATES) {
+ const candidate = NodePath.win32.join(shimDirectory, ...entrySegments);
+ if (isFile(candidate)) {
+ return candidate;
+ }
+ }
+
+ yield* Effect.logWarning(
+ "Claude launcher shim resolved but no known package entry was found next to it; the Claude Agent SDK cannot spawn launcher scripts directly.",
+ { binaryPath, resolvedShimPath: resolved },
+ );
+ return binaryPath;
+ },
+);

apps/server/src/provider/Layers/ClaudeAdapter.ts

@@ -70,6 +70,7 @@ import * as Stream from "effect/Stream";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
  getClaudeModelCapabilities,
@@ -1347,6 +1348,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
  Effect.provideService(Path.Path, path),
  );
+ const claudeSdkExecutablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  const nativeEventLogger =
  options?.nativeEventLogger ??
  (options?.nativeEventLogPath !== undefined
@@ -3405,7 +3410,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
  runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
- const claudeBinaryPath = claudeSettings.binaryPath;
+ const claudeBinaryPath = claudeSdkExecutablePath;
  const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
  const modelSelection =
  input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;

apps/server/src/provider/Layers/ClaudeProvider.ts

@@ -37,6 +37,7 @@ import {
  spawnAndCollect,
  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -588,6 +589,10 @@ const probeClaudeCapabilities = (
  const abort = new AbortController();
  return Effect.gen(function* () {
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+ const executablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  return yield* Effect.tryPromise(async () => {
  const q = claudeQuery({
  // Never yield — we only need initialization data, not a conversation.
@@ -598,7 +603,7 @@ const probeClaudeCapabilities = (
  })(),
  options: {
  persistSession: false,
- pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+ pathToClaudeCodeExecutable: executablePath,
  abortController: abort,
  settingSources: ["user", "project", "local"],
  allowedTools: [],

apps/server/src/provider/Drivers/ClaudeExecutable.test.ts

@@ -0,0 +1,124 @@
+import { describe, expect, it } from "@effect/vitest";
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Effect from "effect/Effect";
+
+import { ClaudeExecutableFileCheck, resolveClaudeSdkExecutablePath } from "./ClaudeExecutable.ts";
+
+const NPM_DIR = "C:\\Users\\dev\\AppData\\Roaming\\npm";
+const NPM_SHIM = `${NPM_DIR}\\claude.cmd`;
+const NPM_PACKAGE_EXE = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\bin\\claude.exe`;
+const NPM_PACKAGE_CLI = `${NPM_DIR}\\node_modules\\@anthropic-ai\\claude-code\\cli.js`;
+
+function withWindowsResolution(input: {
+ readonly resolvedCommand: string | undefined;
+ readonly existingFiles?: ReadonlyArray<string>;
+}) {
+ const existing = new Set(input.existingFiles ?? []);
+ return <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+ effect.pipe(
+ Effect.provideService(HostProcessPlatform, "win32"),
+ Effect.provideService(SpawnExecutableResolution, () => input.resolvedCommand),
+ Effect.provideService(ClaudeExecutableFileCheck, (filePath) => existing.has(filePath)),
+ );
+}
+
+describe("resolveClaudeSdkExecutablePath", () => {
+ it.effect("returns the configured path unchanged on non-Windows platforms", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ Effect.provideService(HostProcessPlatform, "darwin"),
+ Effect.provideService(SpawnExecutableResolution, () => {
+ throw new Error("must not resolve on non-Windows platforms");
+ }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the resolved absolute path for native Windows executables", () =>
+ Effect.gen(function* () {
+ const nativeBinary = "C:\\Users\\dev\\.local\\bin\\claude.exe";
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: nativeBinary }),
+ ),
+ ).toBe(nativeBinary);
+ }),
+ );
+
+ it.effect("follows an npm launcher shim to the packaged native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_EXE, NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("follows .bat and .ps1 launcher shims the same way", () =>
+ Effect.gen(function* () {
+ for (const shim of [`${NPM_DIR}\\claude.bat`, `${NPM_DIR}\\claude.ps1`]) {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: shim,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }
+ }),
+ );
+
+ it.effect("normalizes mixed-case shim extensions before matching", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: `${NPM_DIR}\\claude.CMD`,
+ existingFiles: [NPM_PACKAGE_EXE],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_EXE);
+ }),
+ );
+
+ it.effect("falls back to cli.js when the package ships no native binary", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({
+ resolvedCommand: NPM_SHIM,
+ existingFiles: [NPM_PACKAGE_CLI],
+ }),
+ ),
+ ).toBe(NPM_PACKAGE_CLI);
+ }),
+ );
+
+ it.effect("returns the configured path when a shim has no known package entry", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: NPM_SHIM }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+
+ it.effect("returns the configured path when command resolution finds nothing", () =>
+ Effect.gen(function* () {
+ expect(
+ yield* resolveClaudeSdkExecutablePath("claude", {}).pipe(
+ withWindowsResolution({ resolvedCommand: undefined }),
+ ),
+ ).toBe("claude");
+ }),
+ );
+});

apps/server/src/provider/Drivers/ClaudeExecutable.ts

@@ -0,0 +1,90 @@
+// @effect-diagnostics nodeBuiltinImport:off
+import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
+
+import { HostProcessPlatform } from "@t3tools/shared/hostProcess";
+import { SpawnExecutableResolution } from "@t3tools/shared/shell";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+
+/**
+ * Windows launcher-script extensions that Node cannot spawn without a shell
+ * (`spawn EINVAL` since Node 20.12) and that the Claude Agent SDK therefore
+ * cannot use as `pathToClaudeCodeExecutable`.
+ */
+const WINDOWS_SHIM_EXTENSIONS: ReadonlySet<string> = new Set([".cmd", ".bat", ".ps1"]);
+
+/**
+ * Entry points of the npm `@anthropic-ai/claude-code` package relative to the
+ * global `node_modules` directory that sits next to the npm launcher shim.
+ * Newer package versions ship a native `bin/claude.exe`; older versions only
+ * ship `cli.js`, which the SDK runs with a JavaScript runtime.
+ */
+const NPM_PACKAGE_ENTRY_CANDIDATES = [
+ ["node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"],
+ ["node_modules", "@anthropic-ai", "claude-code", "cli.js"],
+] as const;
+
+export type ExecutableFileCheck = (filePath: string) => boolean;
+
+function isExistingFile(filePath: string): boolean {
+ try {
+ return NodeFS.statSync(filePath).isFile();
+ } catch {
+ return false;
+ }
+}
+
+/** Injectable file-existence check so tests can run against a fake filesystem. */
+export const ClaudeExecutableFileCheck = Context.Reference<ExecutableFileCheck>(
+ "server/provider/Drivers/ClaudeExecutableFileCheck",
+ {
+ defaultValue: () => isExistingFile,
+ },
+);
+
+/**
+ * Resolves the configured Claude binary path into a value the Claude Agent
+ * SDK can spawn directly via `pathToClaudeCodeExecutable`.
+ *
+ * The SDK spawns the given path without a shell and without Windows PATH /
+ * PATHEXT resolution, so a bare command name like `claude` fails with
+ * "native binary not found" and an npm `claude.cmd` shim fails with
+ * `spawn EINVAL`. CLI probes avoid this via `resolveSpawnCommand`, which can
+ * fall back to `shell: true`; the SDK offers no such escape hatch.
+ *
+ * On Windows this resolves the command against PATH/PATHEXT and, when the
+ * result is an npm launcher shim, follows it to the real package entry
+ * (`bin/claude.exe`, or `cli.js` for older package versions). On other
+ * platforms the configured value is returned unchanged.
+ */
+export const resolveClaudeSdkExecutablePath = Effect.fn("resolveClaudeSdkExecutablePath")(
+ function* (binaryPath: string, environment: NodeJS.ProcessEnv): Effect.fn.Return<string> {
+ const platform = yield* HostProcessPlatform;
+ if (platform !== "win32") {
+ return binaryPath;
+ }
+
+ const resolveExecutable = yield* SpawnExecutableResolution;
+ const isFile = yield* ClaudeExecutableFileCheck;
+ const resolved = resolveExecutable(binaryPath, platform, environment) ?? binaryPath;
+ const extension = NodePath.win32.extname(resolved).toLowerCase();
+ if (!WINDOWS_SHIM_EXTENSIONS.has(extension)) {
+ return resolved;
+ }
+
+ const shimDirectory = NodePath.win32.dirname(resolved);
+ for (const entrySegments of NPM_PACKAGE_ENTRY_CANDIDATES) {
+ const candidate = NodePath.win32.join(shimDirectory, ...entrySegments);
+ if (isFile(candidate)) {
+ return candidate;
+ }
+ }
+
+ yield* Effect.logWarning(
+ "Claude launcher shim resolved but no known package entry was found next to it; the Claude Agent SDK cannot spawn launcher scripts directly.",
+ { binaryPath, resolvedShimPath: resolved },
+ );
+ return binaryPath;
+ },
+);

apps/server/src/provider/Layers/ClaudeAdapter.ts

@@ -70,6 +70,7 @@ import * as Stream from "effect/Stream";
 import { resolveAttachmentPath } from "../../attachmentStore.ts";
 import { ServerConfig } from "../../config.ts";
 import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 import {
  getClaudeModelCapabilities,
@@ -1347,6 +1348,10 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, options?.environment).pipe(
  Effect.provideService(Path.Path, path),
  );
+ const claudeSdkExecutablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  const nativeEventLogger =
  options?.nativeEventLogger ??
  (options?.nativeEventLogPath !== undefined
@@ -3405,7 +3410,7 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
  const canUseTool: CanUseTool = (toolName, toolInput, callbackOptions) =>
  runPromise(canUseToolEffect(toolName, toolInput, callbackOptions));
 
- const claudeBinaryPath = claudeSettings.binaryPath;
+ const claudeBinaryPath = claudeSdkExecutablePath;
  const extraArgs = parseCliArgs(claudeSettings.launchArgs).flags;
  const modelSelection =
  input.modelSelection?.instanceId === boundInstanceId ? input.modelSelection : undefined;

apps/server/src/provider/Layers/ClaudeProvider.ts

@@ -37,6 +37,7 @@ import {
  spawnAndCollect,
  type ServerProviderDraft,
 } from "../providerSnapshot.ts";
+import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
 import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
 
 const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -588,6 +589,10 @@ const probeClaudeCapabilities = (
  const abort = new AbortController();
  return Effect.gen(function* () {
  const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
+ const executablePath = yield* resolveClaudeSdkExecutablePath(
+ claudeSettings.binaryPath,
+ claudeEnvironment,
+ );
  return yield* Effect.tryPromise(async () => {
  const q = claudeQuery({
  // Never yield — we only need initialization data, not a conversation.
@@ -598,7 +603,7 @@ const probeClaudeCapabilities = (
  })(),
  options: {
  persistSession: false,
- pathToClaudeCodeExecutable: claudeSettings.binaryPath,
+ pathToClaudeCodeExecutable: executablePath,
  abortController: abort,
  settingSources: ["user", "project", "local"],
  allowedTools: [],