@leo000001/claude-code-mcp 2.4.3 → 2.4.8

package/CHANGELOG.md

@@ -8,6 +8,8 @@
 
 ### Improvements
 
+- Upgrade `@anthropic-ai/claude-agent-sdk` to `^0.2.49` and align MCP-facing schemas with the current SDK surface.
+- Permission mode enum now follows SDK 0.2.49 (`default`, `acceptEdits`, `bypassPermissions`, `plan`, `dontAsk`; `delegate` removed).
 - Session cleanup now marks timed-out running/waiting sessions as `cancelled` for consistent status semantics.
 - `SessionManager.destroy()` now clears in-memory session/runtime maps after aborting active runs, so post-destroy reads are no longer stale.
 - Event buffer eviction now uses batch compaction (instead of repeated `findIndex` + `splice`) and `readEvents` now uses binary search for cursor start.
@@ -15,9 +17,13 @@
 - Runtime tool-discovery updates now notify both tools and resources (internal-tools resource change notification).
 - Enrich compatibility resources with package version, disk-resume diagnostics, and runtime limits.
 - Remove deprecated `claude_code` parameter aliases: top-level `sessionInitTimeoutMs` and `advanced.effort` / `advanced.thinking`.
+- Add support for SDK `promptSuggestions` option passthrough and expose `promptSuggestions` in `advanced`/`diskResumeConfig`.
+- Query consumer now maps additional SDK stream messages (`system/task_started`, `rate_limit`, `prompt_suggestion`) to progress events.
 
 ### Documentation
 
+- Restructure documentation architecture: `AGENTS.md` is now execution-first, while `docs/DESIGN.md` is the single detailed source for interface/mapping semantics.
+- Add explicit doc-governance rules, upgrade submission template, and document DoD to reduce AGENTS/DESIGN duplication regression.
 - Align README/DESIGN/AGENTS with current defaults and behavior (timeout clamp, advanced parameter count, lifecycle semantics).
 - Clarify package positioning as CLI-first and remove stale guidance that implied a public programmatic API surface.
 - Update CONTRIBUTING with local environment requirements (Node/npm and Windows Git Bash notes).

package/README.md

@@ -117,7 +117,7 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
 | `advanced`                   | object           | No       | Advanced/low-frequency parameters (see below)                                                                                                                                                                 |
 
 <details>
-<summary><code>advanced</code> object parameters (20 low-frequency parameters)</summary>
+<summary><code>advanced</code> object parameters (21 low-frequency parameters)</summary>
 
 | Parameter                             | Type               | Description                                                                                                                                                                                                                            |
 | ------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -136,6 +136,7 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
 | `advanced.fallbackModel`              | string             | Fallback model if the primary model fails or is unavailable. Default: none                                                                                                                                                             |
 | `advanced.enableFileCheckpointing`    | boolean            | Enable file checkpointing to track file changes during the session. Default: `false`                                                                                                                                                   |
 | `advanced.includePartialMessages`     | boolean            | When true, includes intermediate streaming messages in the response. Useful for real-time progress monitoring. Default: false                                                                                                          |
+| `advanced.promptSuggestions`          | boolean            | When true, emits post-turn prompt suggestion events (`prompt_suggestion`). Default: `false`                                                                                                                                           |
 | `advanced.strictMcpConfig`            | boolean            | Enforce strict validation of MCP server configurations. Default: `false`                                                                                                                                                               |
 | `advanced.settingSources`             | string[]           | Which filesystem settings to load. Defaults to `["user", "project", "local"]` (loads all settings and CLAUDE.md). Pass `[]` for SDK isolation mode                                                                                     |
 | `advanced.debug`                      | boolean            | Enable debug mode for verbose logging. Default: `false`                                                                                                                                                                                |
@@ -177,7 +178,7 @@ Continue an existing session by sending a follow-up message. The agent retains f
 | `diskResumeConfig`           | object  | No       | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing     |
 
 <details>
-<summary><code>diskResumeConfig</code> object parameters (28 disk-resume-only parameters)</summary>
+<summary><code>diskResumeConfig</code> object parameters (31 disk-resume-only parameters)</summary>
 
 | Parameter                                     | Type               | Description                                                                                     |
 | --------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
@@ -185,6 +186,7 @@ Continue an existing session by sending a follow-up message. The agent retains f
 | `diskResumeConfig.cwd`                        | string             | Working directory. Required for disk resume.                                                    |
 | `diskResumeConfig.allowedTools`               | string[]           | Auto-approved tool names (see `claude_code`). Default: `[]`                                     |
 | `diskResumeConfig.disallowedTools`            | string[]           | Forbidden tool names (see `claude_code`). Default: `[]`                                         |
+| `diskResumeConfig.strictAllowedTools`         | boolean            | Enforce strict allow-list behavior for `allowedTools`. Default: `false`                         |
 | `diskResumeConfig.tools`                      | string[] \| object | Base tool set (see `claude_code`). Default: SDK/Claude Code default                             |
 | `diskResumeConfig.persistSession`             | boolean            | Persist session history to disk. Default: `true`                                                |
 | `diskResumeConfig.maxTurns`                   | number             | Maximum number of agent reasoning steps. Default: SDK/Claude Code default                       |
@@ -205,6 +207,7 @@ Continue an existing session by sending a follow-up message. The agent retains f
 | `diskResumeConfig.fallbackModel`              | string             | Fallback model. Default: none                                                                   |
 | `diskResumeConfig.enableFileCheckpointing`    | boolean            | Enable file checkpointing. Default: `false`                                                     |
 | `diskResumeConfig.includePartialMessages`     | boolean            | Include intermediate streaming messages. Default: `false`                                       |
+| `diskResumeConfig.promptSuggestions`          | boolean            | Emit post-turn prompt suggestion events (`prompt_suggestion`). Default: `false`                |
 | `diskResumeConfig.strictMcpConfig`            | boolean            | Strict MCP config validation. Default: `false`                                                  |
 | `diskResumeConfig.settingSources`             | string[]           | Which filesystem settings to load. Default: `["user", "project", "local"]`                      |
 | `diskResumeConfig.debug`                      | boolean            | Debug mode. Default: `false`                                                                    |

package/dist/index.js

@@ -232,6 +232,7 @@ var SessionManager = class _SessionManager {
       fallbackModel: params.fallbackModel,
       enableFileCheckpointing: params.enableFileCheckpointing,
       includePartialMessages: params.includePartialMessages,
+      promptSuggestions: params.promptSuggestions,
       strictMcpConfig: params.strictMcpConfig,
       settingSources: params.settingSources,
       debug: params.debug,
@@ -328,7 +329,9 @@ var SessionManager = class _SessionManager {
     if (info.status === "waiting_permission") {
       this.finishAllPending(
         sessionId,
-        { behavior: "deny", message: opts?.reason ?? "Session interrupted", interrupt: true },
+        // Similar to cancel(), avoid emitting interrupt=true while the query stream is
+        // being torn down to reduce SDK-level write/teardown races on stdio clients.
+        { behavior: "deny", message: opts?.reason ?? "Session interrupted", interrupt: false },
         "interrupt"
       );
     }
@@ -1236,6 +1239,26 @@ function messageToEvent(msg) {
       }
     };
   }
+  if (msg.type === "system" && msg.subtype === "task_started") {
+    return {
+      type: "progress",
+      data: {
+        type: "task_started",
+        task_id: msg.task_id,
+        tool_use_id: msg.tool_use_id,
+        description: msg.description,
+        task_type: msg.task_type
+      }
+    };
+  }
+  if (msg.type === "rate_limit" || msg.type === "prompt_suggestion") {
+    const rest = { ...msg };
+    delete rest.type;
+    return {
+      type: "progress",
+      data: { type: msg.type, ...rest }
+    };
+  }
   return null;
 }
 function consumeQuery(params) {
@@ -1401,6 +1424,7 @@ function consumeQuery(params) {
     let retryCount = 0;
     let currentStream = activeQuery;
     while (true) {
+      let streamReceivedResult = false;
       try {
         for await (const message of currentStream) {
           if (isSystemInitMessage(message)) {
@@ -1441,6 +1465,7 @@ function consumeQuery(params) {
             continue;
           }
           if (message.type === "result") {
+            streamReceivedResult = true;
             const sessionId2 = message.session_id ?? await getSessionId();
             const agentResult = sdkResultToAgentResult(message);
             const current = params.sessionManager.get(sessionId2);
@@ -1483,7 +1508,7 @@ function consumeQuery(params) {
                 queryInterrupt: void 0
               });
             }
-            return;
+            continue;
           }
           const sessionId = message.session_id ?? await getSessionId();
           const event = messageToEvent(message);
@@ -1501,7 +1526,7 @@ function consumeQuery(params) {
               `Error [${"INTERNAL" /* INTERNAL */}]: query stream ended before receiving session init.`
             )
           );
-        } else if (activeSessionId) {
+        } else if (activeSessionId && !streamReceivedResult) {
           const sessionId = activeSessionId;
           const current = params.sessionManager.get(sessionId);
           if (current && current.status !== "cancelled") {
@@ -1548,6 +1573,9 @@ function consumeQuery(params) {
           );
           return;
         }
+        if (streamReceivedResult) {
+          return;
+        }
         if (!activeSessionId) return;
         const sessionId = activeSessionId;
         if (errClass === "transient" && retryCount < MAX_TRANSIENT_RETRIES) {
@@ -1712,6 +1740,7 @@ function buildOptions(src) {
     opts.enableFileCheckpointing = src.enableFileCheckpointing;
   if (src.includePartialMessages !== void 0)
     opts.includePartialMessages = src.includePartialMessages;
+  if (src.promptSuggestions !== void 0) opts.promptSuggestions = src.promptSuggestions;
   if (src.strictMcpConfig !== void 0) opts.strictMcpConfig = src.strictMcpConfig;
   if (src.settingSources !== void 0) opts.settingSources = src.settingSources;
   else opts.settingSources = DEFAULT_SETTING_SOURCES;
@@ -1750,6 +1779,7 @@ function toSessionCreateParams(input) {
     fallbackModel: src.fallbackModel,
     enableFileCheckpointing: src.enableFileCheckpointing,
     includePartialMessages: src.includePartialMessages,
+    promptSuggestions: src.promptSuggestions,
     strictMcpConfig: src.strictMcpConfig,
     settingSources: src.settingSources ?? DEFAULT_SETTING_SOURCES,
     debug: src.debug,
@@ -2466,11 +2496,14 @@ function detectPathCompatibilityWarnings(session) {
   }
   return warnings;
 }
-function isPosixHomePath(value) {
-  return /^\/home\/[^/\s]+(?:\/|$)/.test(value);
+function isSuspiciousPosixAbsolutePathOnWindows(value) {
+  if (!value.startsWith("/") || value.startsWith("//")) return false;
+  return /^\/home\/[^/\s]+(?:\/|$)/.test(value) || /^\/(?:mnt\/)?[a-zA-Z](?:\/|$)/.test(value) || /^\/(tmp|var|etc|opt|usr|bin|sbin)(?:\/|$)/.test(value);
 }
-function extractPosixHomePath(value) {
-  const match = value.match(/\/home\/[^/\s"'`]+(?:\/[^\s"'`]*)?/);
+function extractSuspiciousPosixAbsolutePath(value) {
+  const match = value.match(
+    /\/(?:home\/[^/\s"'`]+(?:\/[^\s"'`]*)?|(?:mnt\/)?[a-zA-Z](?:\/[^\s"'`]*)?|(?:tmp|var|etc|opt|usr|bin|sbin)(?:\/[^\s"'`]*)?)/
+  );
   return match?.[0];
 }
 function detectPendingPermissionPathWarnings(pending, session) {
@@ -2499,13 +2532,13 @@ function detectPendingPermissionPathWarnings(pending, session) {
     }
     const command = req.input.command;
     if (typeof command === "string") {
-      const embeddedPath = extractPosixHomePath(command);
+      const embeddedPath = extractSuspiciousPosixAbsolutePath(command);
       if (embeddedPath) candidates.push(embeddedPath);
     }
-    const badPath = candidates.find((p) => isPosixHomePath(p));
+    const badPath = candidates.find((p) => isSuspiciousPosixAbsolutePathOnWindows(p));
     if (!badPath) continue;
     warnings.push(
-      `Permission request '${req.requestId}' uses POSIX home path '${badPath}' on Windows. Prefer an absolute Windows path${cwdHint} to avoid out-of-bounds permission prompts.`
+      `Permission request '${req.requestId}' uses POSIX absolute path '${badPath}' on Windows. Prefer an absolute Windows path${cwdHint} to avoid out-of-bounds permission prompts.`
     );
   }
   return warnings;
@@ -3562,7 +3595,7 @@ function registerResources(server, deps) {
 }
 
 // src/server.ts
-var SERVER_VERSION = true ? "2.4.3" : "0.0.0-dev";
+var SERVER_VERSION = true ? "2.4.8" : "0.0.0-dev";
 function createServerContext(serverCwd) {
   const sessionManager = new SessionManager();
   const server = new McpServer(
@@ -3652,6 +3685,7 @@ function createServerContext(serverCwd) {
     fallbackModel: z.string().optional().describe("Default: none"),
     enableFileCheckpointing: z.boolean().optional().describe("Default: false"),
     includePartialMessages: z.boolean().optional().describe("Default: false"),
+    promptSuggestions: z.boolean().optional().describe("Default: false"),
     strictMcpConfig: z.boolean().optional().describe("Default: false"),
     settingSources: z.array(z.enum(["user", "project", "local"])).optional().describe("Default: ['user','project','local']. []=isolation"),
     debug: z.boolean().optional().describe("Default: false"),
@@ -4000,7 +4034,8 @@ var BENIGN_MESSAGE_PATTERNS = [
   "write after end",
   "stream was destroyed",
   "cannot call write after a stream was destroyed",
-  "the pipe is being closed"
+  "the pipe is being closed",
+  "query closed before response received"
 ];
 function isBenignRuntimeError(error) {
   if (!(error instanceof Error)) return false;
@@ -4012,6 +4047,15 @@ function isBenignRuntimeError(error) {
   return BENIGN_MESSAGE_PATTERNS.some((pattern) => message.includes(pattern));
 }
 
+// src/utils/stdin-shutdown.ts
+function decideStdinShutdown(params) {
+  if (!params.stdinUnavailable) return "clear";
+  if (params.isConnected) return "reschedule";
+  if (!params.hasActiveSessions) return "shutdown_now";
+  if (params.elapsedMs >= params.maxWaitMs) return "shutdown_timeout";
+  return "reschedule";
+}
+
 // src/index.ts
 var STDIN_SHUTDOWN_CHECK_MS = 750;
 var STDIN_SHUTDOWN_MAX_WAIT_MS = process.platform === "win32" ? 15e3 : 1e4;
@@ -4088,19 +4132,26 @@ async function main() {
   const evaluateStdinTermination = () => {
     if (closing || stdinClosedAt === void 0) return;
     const stdinUnavailable = process.stdin.destroyed || process.stdin.readableEnded || !process.stdin.readable;
-    if (!stdinUnavailable) {
+    const elapsedMs = Date.now() - stdinClosedAt;
+    const active = hasActiveSessions();
+    const connected = server.isConnected();
+    const decision = decideStdinShutdown({
+      stdinUnavailable,
+      elapsedMs,
+      maxWaitMs: STDIN_SHUTDOWN_MAX_WAIT_MS,
+      hasActiveSessions: active,
+      isConnected: connected
+    });
+    if (decision === "clear") {
       stdinClosedAt = void 0;
       stdinClosedReason = void 0;
       return;
     }
-    const elapsedMs = Date.now() - stdinClosedAt;
-    const active = hasActiveSessions();
-    const connected = server.isConnected();
-    if (!active && !connected) {
+    if (decision === "shutdown_now") {
       void shutdown(`stdin_${stdinClosedReason ?? "closed"}`);
       return;
     }
-    if (elapsedMs >= STDIN_SHUTDOWN_MAX_WAIT_MS) {
+    if (decision === "shutdown_timeout") {
       void shutdown(`stdin_${stdinClosedReason ?? "closed"}_timeout`);
       return;
     }
@@ -4137,7 +4188,9 @@ async function main() {
     void shutdown("SIGHUP");
   });
   process.on("beforeExit", () => {
-    void shutdown("beforeExit");
+    if (!server.isConnected()) {
+      void shutdown("beforeExit");
+    }
   });
   process.on("uncaughtException", handleUnexpectedError);
   process.on("unhandledRejection", handleUnexpectedError);