@leo000001/claude-code-mcp 2.8.0 → 2.8.3

package/dist/index.js

@@ -914,7 +914,7 @@ var SessionManager = class _SessionManager {
 };
 
 // src/tools/claude-code.ts
-import { existsSync as existsSync2, statSync } from "fs";
+import { existsSync as existsSync3, statSync as statSync2 } from "fs";
 
 // src/types.ts
 var EFFORT_LEVELS = ["low", "medium", "high", "max"];
@@ -1949,6 +1949,131 @@ function toSessionCreateParams(input) {
   };
 }
 
+// src/utils/claude-executable.ts
+import { accessSync, constants, existsSync as existsSync2, statSync } from "fs";
+import path3 from "path";
+var DEFAULT_CLAUDE_COMMAND_ENV = "CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND";
+var DEFAULT_CLAUDE_PATH_ENV = "CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH";
+var AUTO_CLAUDE_COMMANDS = ["claude", "claude-internal"];
+function trimEnv(name) {
+  const value = process.env[name];
+  if (typeof value !== "string") return void 0;
+  const trimmed = value.trim();
+  return trimmed === "" ? void 0 : trimmed;
+}
+function normalizeMaybeQuotedPath2(raw) {
+  return path3.normalize(raw.trim().replace(/^"|"$/g, ""));
+}
+function normalizeMaybeQuotedToken(raw) {
+  return raw.trim().replace(/^"|"$/g, "");
+}
+function isExecutableFile(candidate) {
+  try {
+    const stat = statSync(candidate);
+    if (!stat.isFile()) return false;
+    if (process.platform === "win32") return true;
+    accessSync(candidate, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function isUsableExecutablePath(candidate) {
+  return isExecutableFile(candidate);
+}
+function pathEntries2() {
+  const raw = process.env.PATH;
+  if (typeof raw !== "string" || raw.trim() === "") return [];
+  return raw.split(path3.delimiter).map((entry) => entry.trim().replace(/^"|"$/g, "")).filter(Boolean).map((entry) => path3.normalize(entry));
+}
+function windowsExecutableNames(command) {
+  const ext = path3.extname(command);
+  if (ext) return [command];
+  const pathExt = trimEnv("PATHEXT") ?? ".COM;.EXE;.BAT;.CMD";
+  const exts = Array.from(
+    new Set(
+      pathExt.split(";").map((value) => value.trim()).filter(Boolean)
+    )
+  );
+  return exts.map((suffix) => `${command}${suffix.toLowerCase()}`);
+}
+function resolveCommandFromPath(command) {
+  if (command.includes("/") || command.includes("\\")) {
+    throw new Error(
+      `${DEFAULT_CLAUDE_COMMAND_ENV} must be a command name without path separators. Use ${DEFAULT_CLAUDE_PATH_ENV} for filesystem paths.`
+    );
+  }
+  const names = process.platform === "win32" ? windowsExecutableNames(command) : [command];
+  const uniqueNames = Array.from(new Set(names.filter(Boolean)));
+  for (const dir of pathEntries2()) {
+    for (const name of uniqueNames) {
+      const candidate = path3.join(dir, name);
+      if (existsSync2(candidate) && isExecutableFile(candidate)) {
+        return path3.normalize(candidate);
+      }
+    }
+  }
+  return void 0;
+}
+function resolveConfiguredPath(rawPath) {
+  const normalized = normalizeMaybeQuotedPath2(rawPath);
+  const resolved = path3.isAbsolute(normalized) ? normalized : path3.resolve(normalized);
+  if (!isUsableExecutablePath(resolved)) {
+    throw new Error(`${DEFAULT_CLAUDE_PATH_ENV} does not point to an executable file: ${resolved}`);
+  }
+  return path3.normalize(resolved);
+}
+function resolveDefaultClaudeExecutable() {
+  const configuredPath = trimEnv(DEFAULT_CLAUDE_PATH_ENV);
+  const configuredCommandRaw = trimEnv(DEFAULT_CLAUDE_COMMAND_ENV);
+  const configuredCommand = configuredCommandRaw ? normalizeMaybeQuotedToken(configuredCommandRaw) : void 0;
+  if (configuredPath && configuredCommand) {
+    throw new Error(
+      `${DEFAULT_CLAUDE_PATH_ENV} and ${DEFAULT_CLAUDE_COMMAND_ENV} are mutually exclusive; set only one.`
+    );
+  }
+  if (configuredPath) {
+    return {
+      source: "env_path",
+      resolvedPath: resolveConfiguredPath(configuredPath)
+    };
+  }
+  if (configuredCommand) {
+    const resolved = resolveCommandFromPath(configuredCommand);
+    if (!resolved) {
+      throw new Error(
+        `${DEFAULT_CLAUDE_COMMAND_ENV}='${configuredCommand}' was not found in PATH.`
+      );
+    }
+    return {
+      source: "env_command",
+      command: configuredCommand,
+      resolvedPath: resolved
+    };
+  }
+  for (const candidate of AUTO_CLAUDE_COMMANDS) {
+    const resolved = resolveCommandFromPath(candidate);
+    if (!resolved) continue;
+    return {
+      source: candidate === "claude" ? "auto_claude" : "auto_claude_internal",
+      command: candidate,
+      resolvedPath: resolved
+    };
+  }
+  return { source: "sdk_bundled" };
+}
+function getDefaultClaudeExecutablePath() {
+  return resolveDefaultClaudeExecutable().resolvedPath;
+}
+function checkDefaultClaudeExecutableAvailability() {
+  const resolution = resolveDefaultClaudeExecutable();
+  if (!resolution.resolvedPath) return;
+  const commandText = resolution.command ? `, command=${resolution.command}` : "";
+  console.error(
+    `[executable] Default Claude executable resolved: ${resolution.resolvedPath} (source=${resolution.source}${commandText})`
+  );
+}
+
 // src/tools/claude-code.ts
 async function executeClaudeCode(input, sessionManager, serverCwd, toolCache, requestSignal) {
   const cwdProvided = input.cwd !== void 0;
@@ -1961,7 +2086,7 @@ async function executeClaudeCode(input, sessionManager, serverCwd, toolCache, re
     };
   }
   const normalizedCwd = normalizeWindowsPathLike(cwd);
-  if (cwdProvided && !existsSync2(normalizedCwd)) {
+  if (cwdProvided && !existsSync3(normalizedCwd)) {
     return {
       sessionId: "",
       status: "error",
@@ -1970,7 +2095,7 @@ async function executeClaudeCode(input, sessionManager, serverCwd, toolCache, re
   }
   if (cwdProvided) {
     try {
-      if (!statSync(normalizedCwd).isDirectory()) {
+      if (!statSync2(normalizedCwd).isDirectory()) {
         return {
           sessionId: "",
           status: "error",
@@ -2014,7 +2139,7 @@ async function executeClaudeCode(input, sessionManager, serverCwd, toolCache, re
     cwd: normalizeWindowsPathLike(flat.cwd),
     additionalDirectories: flat.additionalDirectories !== void 0 ? normalizeWindowsPathArray(flat.additionalDirectories) : void 0,
     debugFile: flat.debugFile !== void 0 ? normalizeWindowsPathLike(flat.debugFile) : void 0,
-    pathToClaudeCodeExecutable: flat.pathToClaudeCodeExecutable !== void 0 ? normalizeWindowsPathLike(flat.pathToClaudeCodeExecutable) : void 0
+    pathToClaudeCodeExecutable: flat.pathToClaudeCodeExecutable !== void 0 ? normalizeWindowsPathLike(flat.pathToClaudeCodeExecutable) : getDefaultClaudeExecutablePath()
   };
   try {
     const handle = consumeQuery({
@@ -2064,19 +2189,19 @@ async function executeClaudeCode(input, sessionManager, serverCwd, toolCache, re
 }
 
 // src/tools/claude-code-reply.ts
-import { existsSync as existsSync3, statSync as statSync2 } from "fs";
+import { existsSync as existsSync4, statSync as statSync3 } from "fs";
 import os2 from "os";
-import path3 from "path";
+import path4 from "path";
 function normalizeAndAssertCwd(cwd, contextLabel) {
   const normalizedCwd = normalizeWindowsPathLike(cwd);
   const resolvedCwd = resolvePortableTmpAlias(normalizedCwd);
-  if (!existsSync3(resolvedCwd)) {
+  if (!existsSync4(resolvedCwd)) {
     throw new Error(
       `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: ${contextLabel} path does not exist: ${resolvedCwd}`
     );
   }
   try {
-    const stat = statSync2(resolvedCwd);
+    const stat = statSync3(resolvedCwd);
     if (!stat.isDirectory()) {
       throw new Error(
         `Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: ${contextLabel} must be a directory: ${resolvedCwd}`
@@ -2096,7 +2221,7 @@ function resolvePortableTmpAlias(cwd) {
   const normalized = cwd.replace(/\\/g, "/");
   if (normalized === "/tmp") return os2.tmpdir();
   if (normalized.startsWith("/tmp/")) {
-    return path3.join(os2.tmpdir(), normalized.slice("/tmp/".length));
+    return path4.join(os2.tmpdir(), normalized.slice("/tmp/".length));
   }
   return cwd;
 }
@@ -2120,10 +2245,14 @@ function buildOptionsFromDiskResume(dr) {
     throw new Error(`Error [${"INVALID_ARGUMENT" /* INVALID_ARGUMENT */}]: cwd must be provided for disk resume.`);
   }
   const normalizedCwd = normalizeAndAssertCwd(dr.cwd, "disk resume cwd");
-  return buildOptions({
+  const options = buildOptions({
     ...dr,
     cwd: normalizedCwd
   });
+  if (options.pathToClaudeCodeExecutable === void 0) {
+    options.pathToClaudeCodeExecutable = getDefaultClaudeExecutablePath();
+  }
+  return options;
 }
 async function executeClaudeCodeReply(input, sessionManager, toolCache, requestSignal) {
   const permissionRequestTimeoutMs = input.permissionRequestTimeoutMs ?? 6e4;
@@ -2290,6 +2419,10 @@ async function executeClaudeCodeReply(input, sessionManager, toolCache, requestS
   const normalizedCwd = normalizeAndAssertCwd(session.cwd, "session cwd");
   const options = buildOptions(session);
   options.cwd = normalizedCwd;
+  const resolvedDefaultExecutable = options.pathToClaudeCodeExecutable ?? getDefaultClaudeExecutablePath();
+  if (resolvedDefaultExecutable !== void 0) {
+    options.pathToClaudeCodeExecutable = resolvedDefaultExecutable;
+  }
   if (input.forkSession) options.forkSession = true;
   if (input.forkSession && !sessionManager.hasCapacityFor(1)) {
     sessionManager.update(input.sessionId, { status: originalStatus, abortController: void 0 });
@@ -2301,8 +2434,14 @@ async function executeClaudeCodeReply(input, sessionManager, toolCache, requestS
   }
   const sourceOverrides = {
     effort: input.effort ?? session.effort,
-    thinking: input.thinking ?? session.thinking
+    thinking: input.thinking ?? session.thinking,
+    pathToClaudeCodeExecutable: session.pathToClaudeCodeExecutable ?? resolvedDefaultExecutable ?? void 0
   };
+  if (session.pathToClaudeCodeExecutable === void 0 && resolvedDefaultExecutable !== void 0) {
+    sessionManager.update(input.sessionId, {
+      pathToClaudeCodeExecutable: resolvedDefaultExecutable
+    });
+  }
   if (input.effort !== void 0) options.effort = input.effort;
   if (input.thinking !== void 0) options.thinking = input.thinking;
   if (!input.forkSession && (input.effort !== void 0 || input.thinking !== void 0)) {
@@ -2553,8 +2692,8 @@ function groupByCategory(tools) {
 function buildInternalToolsDescription(tools) {
   const grouped = groupByCategory(tools);
   const categories = Object.keys(grouped).sort((a, b) => a.localeCompare(b));
-  let desc = "Start a Claude Code session and return sessionId.\nUse claude_code_check to poll events/results and handle permissions.\n\n";
-  desc += "Internal tools (authoritative list: includeTools=true in claude_code_check):\n";
+  let desc = "Start a background Claude Code run and return sessionId immediately. No final result is returned here.\nMain loop: call claude_code_check(action='poll'), store nextCursor, and keep polling until status becomes idle, error, or cancelled.\nIf actions[] contains permission requests, answer them with claude_code_check(action='respond_permission'). respond_user_input is not supported.\nAdjust polling cadence to progress: poll faster while new events/actions are arriving, and slower when the session is quietly thinking.\nLong-running work is normal: Claude Code can keep working for 10+ minutes, especially with high/max effort, so wait for polling to settle before assuming it is stuck.\nIf you want to continue after a run pauses or finishes, use claude_code_reply with the same sessionId instead of starting a new claude_code session.\nFor runtime-authoritative tool names, call claude_code_check with pollOptions.includeTools=true.\n\n";
+  desc += "Internal tools (runtime list when includeTools=true):\n";
   for (const category of categories) {
     desc += `
 [${category}]
@@ -2564,7 +2703,7 @@ function buildInternalToolsDescription(tools) {
 `;
     }
   }
-  desc += "\nPermission control: allowedTools auto-approves; disallowedTools always denies; others require approval.\n";
+  desc += "\nPermission control: allowedTools pre-approves tools but is not a strict allowlist unless strictAllowedTools=true; disallowedTools always denies; other tools may require approval.\n";
   return desc;
 }
 
@@ -3161,6 +3300,7 @@ function executeClaudeCodeSession(input, sessionManager, requestSignal) {
 // src/resources/register-resources.ts
 import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { createHash } from "crypto";
+import { basename } from "path";
 var RESOURCE_SCHEME = "claude-code-mcp";
 var RESOURCE_URIS = {
   serverInfo: `${RESOURCE_SCHEME}:///server-info`,
@@ -3312,7 +3452,7 @@ function asVersionedPayload(params) {
 }
 function registerResources(server, deps) {
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const resourceSchemaVersion = "1.3";
+  const resourceSchemaVersion = "1.4";
   const mcpProtocolVersion = "2025-03-26";
   const gotchasEntries = buildGotchasEntries();
   const catalogToolNames = new Set(defaultCatalogTools().map((tool) => tool.name));
@@ -3403,7 +3543,7 @@ function registerResources(server, deps) {
     gotchasUri.toString(),
     {
       title: "Gotchas",
-      description: "Practical limits and gotchas when using Claude Code via this MCP server.",
+      description: "High-signal failure modes, symptoms, and remedies for this MCP workflow.",
       mimeType: "text/markdown"
     },
     () => asTextResource(
@@ -3411,7 +3551,18 @@ function registerResources(server, deps) {
       [
         "# claude-code-mcp: gotchas",
         "",
-        ...gotchasEntries.map((entry) => `- ${entry.title}. ${entry.remedy}`),
+        "Check these before assuming the session is broken.",
+        "",
+        ...gotchasEntries.flatMap((entry) => [
+          `## ${entry.title}`,
+          `- Severity: ${entry.severity}`,
+          `- Applies to: ${entry.appliesTo.join(", ")}`,
+          `- Symptom: ${entry.symptom}`,
+          `- Detection: ${entry.detection}`,
+          `- Remedy: ${entry.remedy}`,
+          ...entry.example ? [`- Example: ${entry.example}`] : [],
+          ""
+        ]),
         ""
       ].join("\n"),
       "text/markdown"
@@ -3424,7 +3575,7 @@ function registerResources(server, deps) {
     quickstartUri.toString(),
     {
       title: "Quickstart",
-      description: "Minimal async polling flow for claude_code / claude_code_check.",
+      description: "Canonical async start, poll, permission, and continue flow for MCP callers.",
       mimeType: "text/markdown"
     },
     () => asTextResource(
@@ -3432,14 +3583,43 @@ function registerResources(server, deps) {
       [
         "# claude-code-mcp quickstart",
         "",
-        "1. Call `claude_code` with `{ prompt }` and keep `sessionId`.",
-        "2. Poll with `claude_code_check(action='poll')` using `nextCursor`.",
-        "3. If actions are returned, respond with `claude_code_check(action='respond_permission')`.",
-        "4. Continue polling until status becomes `idle` / `error` / `cancelled`.",
+        "## Required state",
+        "",
+        "Persist these client-side:",
+        "- `sessionId`: returned by `claude_code` / `claude_code_reply`.",
+        "- `nextCursor`: returned by each `claude_code_check(action='poll')` call.",
+        "",
+        "## Main loop",
+        "",
+        "1. Call `claude_code` with `{ prompt }`.",
+        "2. Store `sessionId` from the start response.",
+        "3. Poll with `claude_code_check(action='poll')`, passing the previous `nextCursor` back as `cursor`.",
+        "4. If `actions[]` contains a permission request, answer it with `claude_code_check(action='respond_permission')`.",
+        "5. Continue polling until `status` becomes `idle`, `error`, or `cancelled`.",
+        "",
+        "## Continue an existing run",
+        "",
+        "- If Claude Code stops and you want to keep going, call `claude_code_reply` with the existing `sessionId` instead of starting a fresh `claude_code` session.",
+        "- `claude_code_reply` requires a persistent session, or `diskResumeConfig` when disk resume fallback is enabled and the in-memory session is missing.",
+        "",
+        "## Reminders",
+        "",
+        "- This backend is asynchronous: `claude_code` and `claude_code_reply` start work, and the final result arrives later via polling.",
+        "- Claude Code may keep working for 10+ minutes on larger tasks, especially with `effort='high'` or `effort='max'`; keep polling and be patient before treating it as stuck.",
+        "- Adjust poll intervals to the current progress: poll faster while new events or permission actions are arriving, and slower while the session is quietly thinking with no new output.",
+        "- `model` is optional. If omitted, Claude Code chooses the effective model from its own defaults/settings.",
+        "- `allowedTools` is pre-approval by default; set `strictAllowedTools=true` when you need a strict allowlist.",
+        "- `allow_for_session` usually works best when the same tool will be used repeatedly in one session.",
+        "",
+        "## Common mistakes",
+        "",
+        "- Do not call `claude_code_reply` on a non-persistent session if you expect to continue later; keep `advanced.persistSession=true`.",
+        "- Store `nextCursor` and feed it back into the next `claude_code_check(action='poll')`; otherwise you will keep replaying old events.",
+        "- On Windows, set `CLAUDE_CODE_GIT_BASH_PATH` or Claude Code may fail before the session starts.",
+        "- If `decision='allow_for_session'` still shows a permission request, inspect `actions[].suggestions` / `blockedPath`; directory access may need a more specific permission update.",
         "",
         "Notes:",
-        "- `respond_user_input` is not supported on this backend.",
-        "- `allowedTools` is pre-approval by default; set `strictAllowedTools=true` for strict allowlist behavior.",
+        "- `respond_user_input` is not supported. Use only `respond_permission` for approvals.",
         "- OpenCode/Codex-style clients usually work best when they store `sessionId` + `nextCursor` and answer approvals with `decision=allow_for_session`.",
         "- Prefer `responseMode='delta_compact'` for high-frequency polling."
       ].join("\n"),
@@ -3499,6 +3679,7 @@ function registerResources(server, deps) {
       const diskResumeEnabled = process.env.CLAUDE_CODE_MCP_ALLOW_DISK_RESUME === "1";
       const resumeSecretConfigured = typeof process.env.CLAUDE_CODE_MCP_RESUME_SECRET === "string" && process.env.CLAUDE_CODE_MCP_RESUME_SECRET.trim() !== "";
       const runtimeToolStats = deps.sessionManager.getRuntimeToolStats();
+      const defaultClaudeExecutable = resolveDefaultClaudeExecutable();
       const toolCatalogCount = deps.toolCache.getTools().length;
       const detectedMismatches = [];
       if (runtimeToolStats.sessionsWithInitTools > 0 && runtimeToolStats.runtimeDiscoveredUniqueCount < toolCatalogCount) {
@@ -3527,6 +3708,12 @@ function registerResources(server, deps) {
           enabled: diskResumeEnabled,
           resumeSecretConfigured
         },
+        defaultClaudeExecutable: {
+          source: defaultClaudeExecutable.source,
+          command: defaultClaudeExecutable.command,
+          resolvedFileName: defaultClaudeExecutable.resolvedPath ? basename(defaultClaudeExecutable.resolvedPath) : void 0,
+          usingBundled: defaultClaudeExecutable.resolvedPath === void 0
+        },
         features: {
           resources: true,
           resourceTemplates: true,
@@ -3553,8 +3740,10 @@ function registerResources(server, deps) {
         },
         guidance: [
           "Some clients cache tool descriptions at connect time. Prefer claude_code_check(pollOptions.includeTools=true) for runtime-authoritative tool lists.",
+          "Treat tool descriptions and MCP resources as agent-visible guidance; do not assume README-level documentation is visible to the model.",
           "Use allowedTools/disallowedTools only with exact runtime tool names.",
           "Set strictAllowedTools=true when you need allowedTools to behave as a strict allowlist.",
+          "Default Claude executable selection prefers request path, then CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH, then CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND, then auto-detected 'claude'/'claude-internal', then SDK-bundled.",
           "This server assumes MCP client and server run on the same machine/platform.",
           "For high-frequency status checks, prefer responseMode='delta_compact'.",
           "respond_user_input is not supported on this backend; use poll/respond_permission flow."
@@ -3723,7 +3912,8 @@ function registerResources(server, deps) {
             detectedMismatches: [],
             recommendations: [
               "Prefer responseMode='delta_compact' for fast status loops.",
-              "Enable pollOptions.includeTools=true when exact runtime tool names are required."
+              "Enable pollOptions.includeTools=true when exact runtime tool names are required.",
+              "Do not assume human-facing README guidance is visible to the agent; keep critical calling rules in tool descriptions or MCP resources."
             ]
           };
         }
@@ -3734,7 +3924,8 @@ function registerResources(server, deps) {
             recommendations: [
               "Use resources and resource templates for low-latency diagnostics.",
               "Use allowedTools/disallowedTools with exact runtime names.",
-              "Enable strictAllowedTools when running in locked-down governance mode."
+              "Enable strictAllowedTools when running in locked-down governance mode.",
+              "Keep protocol-critical calling rules in tool descriptions or resources, not only in README-like docs."
             ]
           };
         }
@@ -3755,7 +3946,8 @@ function registerResources(server, deps) {
           detectedMismatches: [],
           recommendations: [
             "Persist nextCursor and de-duplicate by event.id.",
-            "Use responseMode='delta_compact' for high-frequency polling, full mode only for diagnostics."
+            "Use responseMode='delta_compact' for high-frequency polling, full mode only for diagnostics.",
+            "Do not assume repository docs are model-visible; tool descriptions and resources are safer places for runtime guidance."
           ]
         };
       })();
@@ -3783,7 +3975,7 @@ function registerResources(server, deps) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "2.8.0" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.8.3" : "0.0.0-dev";
 function createServerContext(serverCwd) {
   const sessionManager = new SessionManager();
   const server = new McpServer(
@@ -3791,7 +3983,7 @@ function createServerContext(serverCwd) {
       name: "claude-code-mcp",
       version: SERVER_VERSION,
       title: "Claude Code MCP",
-      description: "MCP server that runs Claude Code via the Claude Agent SDK with async polling and interactive permissions.",
+      description: "MCP server that runs Claude Code via the Claude Agent SDK. Starts and replies return quickly; callers poll with claude_code_check and answer permission requests explicitly.",
       websiteUrl: "https://github.com/xihuai18/claude-code-mcp",
       icons: []
     },
@@ -3821,11 +4013,13 @@ function createServerContext(serverCwd) {
   const agentDefinitionSchema = z.object({
     description: z.string(),
     prompt: z.string(),
-    tools: z.array(z.string()).optional().describe("Default: inherit"),
+    tools: z.array(z.string()).optional().describe("Allowed tool names for this subagent. Default: inherit"),
     disallowedTools: z.array(z.string()).optional().describe("Default: none"),
     model: z.string().optional().describe("Default: inherit"),
     maxTurns: z.number().int().positive().optional().describe("Default: none"),
-    mcpServers: z.array(z.union([z.string(), z.record(z.string(), z.unknown())])).optional().describe("Default: inherit"),
+    mcpServers: z.array(z.union([z.string(), z.record(z.string(), z.unknown())])).optional().describe(
+      "Additional MCP server names or inline process-transport specs for this subagent. Default: inherit"
+    ),
     skills: z.array(z.string()).optional().describe("Default: none"),
     criticalSystemReminder_EXPERIMENTAL: z.string().optional().describe("Default: none")
   });
@@ -3848,7 +4042,7 @@ function createServerContext(serverCwd) {
     z.object({ type: z.literal("adaptive") }),
     z.object({
       type: z.literal("enabled"),
-      budgetTokens: z.number().int().positive()
+      budgetTokens: z.number().int().positive().optional()
     }),
     z.object({ type: z.literal("disabled") })
   ]);
@@ -3859,51 +4053,71 @@ function createServerContext(serverCwd) {
     schema: z.record(z.string(), z.unknown())
   });
   const sharedOptionFieldsSchemaShape = {
-    tools: toolsConfigSchema.optional().describe("Tool set. Default: SDK"),
+    tools: toolsConfigSchema.optional().describe(
+      "Visible built-in tool set. Use this to restrict what Claude can see/call: string[] of exact tool names, [] to disable built-ins, or {type:'preset',preset:'claude_code'}. Default: SDK"
+    ),
     persistSession: z.boolean().optional().describe("Default: true"),
-    agents: z.record(z.string(), agentDefinitionSchema).optional().describe("Default: none"),
+    agents: z.record(z.string(), agentDefinitionSchema).optional().describe("Custom subagents keyed by agent name. Default: none"),
     agent: z.string().optional().describe("Default: none"),
     maxBudgetUsd: z.number().positive().optional().describe("Default: none"),
     betas: z.array(z.string()).optional().describe("Default: none"),
     additionalDirectories: z.array(z.string()).optional().describe("Default: none"),
-    outputFormat: outputFormatSchema.optional().describe("Default: none"),
-    pathToClaudeCodeExecutable: z.string().optional().describe("Default: SDK-bundled"),
-    mcpServers: z.record(z.string(), z.record(z.string(), z.unknown())).optional().describe("Default: none"),
-    sandbox: z.record(z.string(), z.unknown()).optional().describe("Default: none"),
+    outputFormat: outputFormatSchema.optional().describe("Structured output config: {type:'json_schema', schema:{...}}. Default: none"),
+    pathToClaudeCodeExecutable: z.string().optional().describe(
+      "Explicit Claude executable path. Default: auto-detect 'claude', then 'claude-internal', else SDK-bundled. Server env vars can override the default."
+    ),
+    mcpServers: z.record(z.string(), z.record(z.string(), z.unknown())).optional().describe("MCP server configs keyed by server name. Default: none"),
+    sandbox: z.record(z.string(), z.unknown()).optional().describe(
+      "Sandbox behavior config object. This controls sandbox behavior, not the actual allow/deny permission rules. Default: none"
+    ),
     fallbackModel: z.string().optional().describe("Default: none"),
     enableFileCheckpointing: z.boolean().optional().describe("Default: false"),
-    toolConfig: z.record(z.string(), z.unknown()).optional().describe("Default: none"),
+    toolConfig: z.record(z.string(), z.unknown()).optional().describe(
+      "Per-tool built-in config object, e.g. {askUserQuestion:{previewFormat:'markdown'|'html'}}. Default: none"
+    ),
     includePartialMessages: z.boolean().optional().describe("Default: false"),
     promptSuggestions: z.boolean().optional().describe("Default: false"),
     agentProgressSummaries: z.boolean().optional().describe("Default: false"),
     strictMcpConfig: z.boolean().optional().describe("Default: false"),
-    settings: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe("Default: none"),
+    settings: z.union([z.string(), z.record(z.string(), z.unknown())]).optional().describe(
+      "Path to a settings JSON file or an inline settings object. Loaded as highest-priority flag settings. Default: none"
+    ),
     settingSources: z.array(z.enum(["user", "project", "local"])).optional().describe("Default: ['user','project','local']. []=isolation"),
     debug: z.boolean().optional().describe("Default: false"),
-    debugFile: z.string().optional().describe("Default: none"),
-    env: z.record(z.string(), z.string().optional()).optional().describe("Default: none")
+    debugFile: z.string().optional().describe("Write debug logs to this file and implicitly enable debug. Default: none"),
+    env: z.record(z.string(), z.string().optional()).optional().describe(
+      "Environment variables merged over process.env before launching Claude Code. Default: none"
+    )
   };
   const advancedOptionFieldsSchemaShape = {
     ...sharedOptionFieldsSchemaShape
   };
   const diskResumeOptionFieldsSchemaShape = {
     ...sharedOptionFieldsSchemaShape,
-    effort: effortOptionSchema.describe("Default: SDK"),
-    thinking: thinkingOptionSchema.describe("Default: SDK")
+    effort: effortOptionSchema.describe(
+      "Effort string: 'low' | 'medium' | 'high' | 'max'. Default: SDK"
+    ),
+    thinking: thinkingOptionSchema.describe(
+      "Thinking config object, not a string. Use {type:'adaptive'} | {type:'enabled', budgetTokens?:N} | {type:'disabled'}. Default: SDK"
+    )
   };
   const advancedOptionsSchema = z.object({
     ...advancedOptionFieldsSchemaShape,
-    sessionInitTimeoutMs: z.number().int().positive().optional().describe("Default: 10000")
+    sessionInitTimeoutMs: z.number().int().positive().optional().describe("Server init wait timeout in ms; not forwarded to SDK Options. Default: 10000")
   }).optional().describe("Default: none");
   const diskResumeConfigSchema = z.object({
     resumeToken: z.string(),
     cwd: z.string(),
-    allowedTools: z.array(z.string()).optional().describe("Default: []"),
-    disallowedTools: z.array(z.string()).optional().describe("Default: []"),
-    strictAllowedTools: z.boolean().optional().describe("Default: false"),
+    allowedTools: z.array(z.string()).optional().describe("Pre-approved tool names for resumed execution. Default: []"),
+    disallowedTools: z.array(z.string()).optional().describe("Always-denied tool names. Default: []"),
+    strictAllowedTools: z.boolean().optional().describe(
+      "Server-side strict allowlist toggle; not forwarded to SDK Options. Default: false"
+    ),
     maxTurns: z.number().int().positive().optional().describe("Default: SDK"),
     model: z.string().optional().describe("Default: SDK"),
-    systemPrompt: systemPromptSchema.optional().describe("Default: SDK"),
+    systemPrompt: systemPromptSchema.optional().describe(
+      "System prompt config: string, {type:'preset',preset:'claude_code'}, or {type:'preset',preset:'claude_code',append:'...'}. Default: SDK"
+    ),
     resumeSessionAt: z.string().optional().describe("Default: none"),
     ...diskResumeOptionFieldsSchemaShape
   }).optional().describe("Default: none");
@@ -3964,17 +4178,29 @@ function createServerContext(serverCwd) {
     {
       description: buildInternalToolsDescription(toolCache.getTools()),
       inputSchema: {
-        prompt: z.string().describe("Prompt"),
+        prompt: z.string().describe(
+          "Prompt for a new background run. The final result arrives later via claude_code_check, not this call. Store nextCursor from polls and reuse sessionId with claude_code_reply if you want to continue later."
+        ),
         cwd: z.string().optional().describe("Working dir. Default: server cwd"),
-        allowedTools: z.array(z.string()).optional().describe("Default: []"),
-        disallowedTools: z.array(z.string()).optional().describe("Default: []"),
-        strictAllowedTools: z.boolean().optional().describe("Default: false"),
+        allowedTools: z.array(z.string()).optional().describe(
+          "Pre-approved tool names. Default: []. This is not a strict allowlist unless strictAllowedTools=true."
+        ),
+        disallowedTools: z.array(z.string()).optional().describe("Always-denied tool names. Default: []"),
+        strictAllowedTools: z.boolean().optional().describe("Default: false. When true, tools outside allowedTools are denied."),
         maxTurns: z.number().int().positive().optional().describe("Default: SDK"),
         model: z.string().optional().describe("Default: SDK"),
-        effort: effortOptionSchema.describe("Default: SDK"),
-        thinking: thinkingOptionSchema.describe("Default: SDK"),
-        systemPrompt: systemPromptSchema.optional().describe("Default: SDK"),
-        permissionRequestTimeoutMs: z.number().int().positive().optional().describe("Default: 60000, clamped to 300000"),
+        effort: effortOptionSchema.describe(
+          "Effort string: 'low' | 'medium' | 'high' | 'max'. Default: SDK"
+        ),
+        thinking: thinkingOptionSchema.describe(
+          "Thinking config object, not a string. Use {type:'adaptive'} | {type:'enabled', budgetTokens?:N} | {type:'disabled'}. Default: SDK"
+        ),
+        systemPrompt: systemPromptSchema.optional().describe(
+          "System prompt config: string, {type:'preset',preset:'claude_code'}, or {type:'preset',preset:'claude_code',append:'...'}. Default: SDK"
+        ),
+        permissionRequestTimeoutMs: z.number().int().positive().optional().describe(
+          "Server permission wait timeout in ms; not forwarded to SDK Options. Default: 60000, clamped to 300000"
+        ),
         advanced: advancedOptionsSchema
       },
       outputSchema: startResultSchema,
@@ -4028,16 +4254,26 @@ function createServerContext(serverCwd) {
   server.registerTool(
     "claude_code_reply",
     {
-      description: "Send a follow-up to an existing session. Returns immediately; use claude_code_check to poll.",
+      description: "Send a follow-up to an existing session. Reuse the same sessionId instead of starting a new claude_code session when you want to continue. Returns immediately; poll with claude_code_check. Use diskResumeConfig only when the in-memory session is missing and disk resume is enabled.",
       inputSchema: {
-        sessionId: z.string().describe("Session ID"),
-        prompt: z.string().describe("Prompt"),
+        sessionId: z.string().describe(
+          "Session ID from claude_code or an earlier claude_code_reply. Prefer this over starting a fresh claude_code session. Reply works only for persistent sessions, or with diskResumeConfig when disk resume fallback is enabled."
+        ),
+        prompt: z.string().describe("Follow-up prompt for the existing session."),
         forkSession: z.boolean().optional().describe("Default: false"),
-        effort: effortOptionSchema.describe("Default: SDK"),
-        thinking: thinkingOptionSchema.describe("Default: SDK"),
-        sessionInitTimeoutMs: z.number().int().positive().optional().describe("Default: 10000"),
-        permissionRequestTimeoutMs: z.number().int().positive().optional().describe("Default: 60000, clamped to 300000"),
-        diskResumeConfig: diskResumeConfigSchema
+        effort: effortOptionSchema.describe(
+          "Effort string: 'low' | 'medium' | 'high' | 'max'. Default: SDK"
+        ),
+        thinking: thinkingOptionSchema.describe(
+          "Thinking config object, not a string. Use {type:'adaptive'} | {type:'enabled', budgetTokens?:N} | {type:'disabled'}. Default: SDK"
+        ),
+        sessionInitTimeoutMs: z.number().int().positive().optional().describe("Default: 10000. Applies when forkSession=true."),
+        permissionRequestTimeoutMs: z.number().int().positive().optional().describe(
+          "Server permission wait timeout in ms; not forwarded to SDK Options. Default: 60000, clamped to 300000"
+        ),
+        diskResumeConfig: diskResumeConfigSchema.describe(
+          "Default: none. Use only when the in-memory session is missing and the server allows disk resume."
+        )
       },
       outputSchema: startResultSchema,
       annotations: {
@@ -4086,9 +4322,11 @@ function createServerContext(serverCwd) {
     {
       description: "List, inspect, cancel, or interrupt sessions.",
       inputSchema: {
-        action: z.enum(SESSION_ACTIONS),
-        sessionId: z.string().optional().describe("Required for get/cancel/interrupt"),
-        includeSensitive: z.boolean().optional().describe("Default: false")
+        action: z.enum(SESSION_ACTIONS).describe("Session operation: list, get, cancel, or interrupt."),
+        sessionId: z.string().optional().describe("Required for get/cancel/interrupt."),
+        includeSensitive: z.boolean().optional().describe(
+          "Default: false. Exposes more session fields, but some secrets remain redacted."
+        )
       },
       outputSchema: sessionResultSchema,
       annotations: {
@@ -4134,19 +4372,31 @@ function createServerContext(serverCwd) {
   server.registerTool(
     "claude_code_check",
     {
-      description: "Poll session events or respond to permission requests.",
+      description: "Poll session state or answer a pending permission request. Main loop: call action='poll', persist nextCursor, and use action='respond_permission' for approvals. respond_user_input is not supported.",
       inputSchema: {
-        action: z.enum(CHECK_ACTIONS),
-        sessionId: z.string().describe("Session ID"),
-        cursor: z.number().int().nonnegative().optional().describe("Default: 0"),
-        responseMode: z.enum(CHECK_RESPONSE_MODES).optional().describe("Default: 'minimal'. Use 'delta_compact' for lightweight polling."),
+        action: z.enum(CHECK_ACTIONS).describe(
+          "'poll' fetches new events/actions/result; 'respond_permission' answers one pending permission request."
+        ),
+        sessionId: z.string().describe("Session ID returned by claude_code or claude_code_reply."),
+        cursor: z.number().int().nonnegative().optional().describe(
+          "Default: 0. Pass the previous nextCursor to avoid replaying old buffered events."
+        ),
+        responseMode: z.enum(CHECK_RESPONSE_MODES).optional().describe(
+          "Default: 'minimal'. Use 'delta_compact' for lightweight high-frequency polling; use 'full' mainly for diagnostics."
+        ),
         maxEvents: z.number().int().positive().optional().describe("Default: 200 (minimal), unlimited (full/delta_compact)"),
-        requestId: z.string().optional().describe("Default: none"),
-        decision: z.enum(["allow", "deny", "allow_for_session"]).optional().describe("Default: none"),
-        denyMessage: z.string().optional().describe("Default: 'Permission denied by caller'"),
-        interrupt: z.boolean().optional().describe("Default: false"),
+        requestId: z.string().optional().describe("Default: none. Required for action='respond_permission'."),
+        decision: z.enum(["allow", "deny", "allow_for_session"]).optional().describe(
+          "Default: none. Required for action='respond_permission'. 'allow_for_session' reduces repeated prompts in the same session."
+        ),
+        denyMessage: z.string().optional().describe("Default: 'Permission denied by caller'. Used only with decision='deny'."),
+        interrupt: z.boolean().optional().describe(
+          "Default: false. When true, a deny decision also interrupts the whole session."
+        ),
         pollOptions: z.object({
-          includeTools: z.boolean().optional().describe("Default: false"),
+          includeTools: z.boolean().optional().describe(
+            "Default: false. When true, include runtime-discovered availableTools; use this when exact tool names matter."
+          ),
           includeEvents: z.boolean().optional().describe("Default: true"),
           includeActions: z.boolean().optional().describe("Default: true"),
           includeResult: z.boolean().optional().describe("Default: true"),
@@ -4156,11 +4406,13 @@ function createServerContext(serverCwd) {
           includeTerminalEvents: z.boolean().optional().describe("Default: full=true, minimal/delta_compact=false"),
           includeProgressEvents: z.boolean().optional().describe("Default: full=true, minimal/delta_compact=false"),
           maxBytes: z.number().int().positive().optional().describe("Default: unlimited")
-        }).optional().describe("Default: none"),
+        }).optional().describe("Default: none. Advanced polling payload controls for action='poll'."),
         permissionOptions: z.object({
           updatedInput: z.record(z.string(), z.unknown()).optional().describe("Default: none"),
           updatedPermissions: z.array(z.record(z.string(), z.unknown())).optional().describe("Default: none")
-        }).optional().describe("Default: none")
+        }).optional().describe(
+          "Default: none. Advanced permission response overrides for action='respond_permission'."
+        )
       },
       outputSchema: checkResultSchema,
       annotations: {
@@ -4396,10 +4648,11 @@ async function main() {
   process.stdin.on("error", handleStdinError);
   process.stdin.on("end", onStdinEnd);
   process.stdin.on("close", onStdinClose);
+  checkWindowsBashAvailability();
+  checkDefaultClaudeExecutableAvailability();
   await server.connect(transport);
   server.sendToolListChanged();
   server.sendResourceListChanged();
-  checkWindowsBashAvailability();
   try {
     if (transport && server) {
       await server.sendLoggingMessage({