@leo000001/claude-code-mcp 2.8.0 → 2.8.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/CHANGELOG.md +7 -0
  2. package/README.md +116 -85
  3. package/dist/index.js +334 -81
  4. package/dist/index.js.map +1 -1
  5. package/package.json +2 -1
package/CHANGELOG.md CHANGED
@@ -8,11 +8,18 @@
8
8
  - Expand SDK stream/event mapping for `rate_limit_event`, `system/api_retry`, `system/local_command_output`, `system/elicitation_complete`, `system/compact_boundary`, and partial `stream_event` output.
9
9
  - Preserve newer SDK metadata in session/results, including `fastModeState` and richer permission prompt labels (`title`, `displayName`).
10
10
  - Prefer SDK permission `suggestions` for `allow_for_session` responses and sync session metadata from `system/init` (for example actual model / permission mode).
11
+ - Add default Claude executable resolution with explicit env overrides (`CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` / `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND`) and auto-detection order `claude` -> `claude-internal` -> SDK-bundled.
11
12
 
12
13
  ### Documentation
13
14
 
14
15
  - Add OpenCode-specific setup and usage guidance, including local MCP config examples and async polling recommendations.
15
16
  - Sync README and DESIGN option/message matrices with the current SDK 0.2.81 surface.
17
+ - Add usage reminders in model-visible guidance: long Claude Code runs are normal, and follow-up questions should use `claude_code_reply` with the existing session.
18
+ - Separate agent-visible MCP guidance from repo-only documentation, and move more protocol-critical rules into tool descriptions and resources.
19
+
20
+ ### Tests
21
+
22
+ - Add a reusable stdio metadata smoke script to verify agent-visible tool/resource guidance through a real MCP client transport.
16
23
 
17
24
  ## 2.5.0 (2026-02-27)
18
25
 
package/README.md CHANGED
@@ -10,6 +10,16 @@ Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sd
10
10
 
11
11
  This package is **CLI-first**: it is intended to run as an MCP server process (`npx @leo000001/claude-code-mcp`), not as a stable programmatic library API.
12
12
 
13
+ ## Visibility Boundary
14
+
15
+ Not every piece of documentation below is visible to an MCP-connected coding agent.
16
+
17
+ - **Usually visible to the agent:** MCP tool names, tool descriptions, input field descriptions, and MCP resources that the client explicitly reads.
18
+ - **Not safe to assume visible:** this `README.md`, `docs/DESIGN.md`, `AGENTS.md`, and other repository files unless the client or orchestrator copies that content into the model context.
19
+ - **Authoring rule:** keep protocol-critical calling rules in tool descriptions and MCP resources first; mirror them in README for humans, but do not rely on README alone.
20
+
21
+ In practice, the most important runtime rules are duplicated in the `claude_code*` tool descriptions and the `quickstart` / `gotchas` / `compat-report` resources so async polling clients can succeed even when they never read this file.
22
+
13
23
  ## Features
14
24
 
15
25
  - **4 tools** covering the full agent lifecycle: start, continue, check/poll, manage
@@ -30,9 +40,10 @@ See `CHANGELOG.md` for release history.
30
40
  - **Node.js >= 18** is required.
31
41
  - **Same-platform deployment** — this MCP server is designed to run on the same machine as the MCP client. It communicates via stdio (child process), reads local Claude configuration files from `~/.claude/`, and accesses the local file system directly. Remote deployment is not supported.
32
42
 
33
- This MCP server uses the [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) package, which **bundles its own Claude Code CLI** (`cli.js`). It does not use the `claude` binary from your system PATH.
43
+ This MCP server uses the [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) package, which **bundles its own Claude Code CLI** (`cli.js`). When no explicit `pathToClaudeCodeExecutable` is provided, this server now prefers a detected local `claude` command, then `claude-internal`, and falls back to the SDK-bundled CLI if neither is found.
34
44
 
35
45
  - The SDK bundles a Claude Code CLI; its version generally tracks the SDK package version, but the exact scheme is not guaranteed
46
+ - Default executable resolution order is: request-level `pathToClaudeCodeExecutable` -> `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` -> `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND` -> auto-detected `claude` -> auto-detected `claude-internal` -> SDK-bundled CLI
36
47
  - **Configuration is shared** — the bundled CLI reads API keys and settings from `~/.claude/`, same as the system-installed `claude`
37
48
  - **All local settings are loaded by default** — unlike the raw SDK (which defaults to isolation mode), this MCP server loads `user`, `project`, and `local` settings automatically, including `CLAUDE.md` project context. Pass `advanced.settingSources: []` to opt out
38
49
  - You must have Claude Code configured (API key set up) before using this MCP server: see [Claude Code documentation](https://docs.anthropic.com/en/docs/claude-code/overview)
@@ -122,16 +133,19 @@ npm start
122
133
 
123
134
  Start a new Claude Code session. The agent autonomously performs coding tasks: reading/writing files, running shell commands, searching code, managing git, and interacting with APIs.
124
135
 
136
+ Important protocol note: this call starts background work and returns quickly with `sessionId`; it does not return the final result. Callers must poll `claude_code_check(action="poll")`, persist `nextCursor`, and use `claude_code_reply` to continue the same session later.
137
+
125
138
  | Parameter | Type | Required | Description |
126
139
  | ---------------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
127
140
  | `prompt` | string | Yes | Task or question for Claude Code |
128
141
  | `cwd` | string | No | Working directory (defaults to server cwd) |
129
- | `allowedTools` | string[] | No | Auto-approved tool names. Default: `[]` (none). Tools not in `allowedTools`/`disallowedTools` may surface permission requests via `claude_code_check`. Example: `["Bash", "Read", "Write", "Edit"]` |
142
+ | `allowedTools` | string[] | No | Auto-approved tool names. Default: `[]` (none). This is not a strict allowlist unless `strictAllowedTools=true`. Example: `["Bash", "Read", "Write", "Edit"]` |
143
+ | `strictAllowedTools` | boolean | No | Server-side strict allowlist toggle. When `true`, tools outside `allowedTools` are denied. Default: `false` |
130
144
  | `disallowedTools` | string[] | No | Forbidden tool names. Default: `[]` (none). SDK behavior: disallowed tools are removed from the model's context. Takes precedence over `allowedTools` and will be denied even if later approved interactively |
131
145
  | `maxTurns` | number | No | Maximum number of agent reasoning steps. Each step may involve one or more tool calls. Default: SDK/Claude Code default |
132
146
  | `model` | string | No | Model to use (e.g. `"claude-sonnet-4-5-20250929"`). Default: SDK/Claude Code default |
133
- | `effort` | string | No | Effort level: `"low"`, `"medium"`, `"high"`, `"max"`. Default: SDK/Claude Code default |
134
- | `thinking` | object | No | Thinking mode: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens: N }`, or `{ type: "disabled" }`. Default: SDK/Claude Code default |
147
+ | `effort` | string | No | Effort string: `"low"`, `"medium"`, `"high"`, `"max"`. Default: SDK/Claude Code default |
148
+ | `thinking` | object | No | Thinking config object, not a string: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens?: N }`, or `{ type: "disabled" }`. Do not pass `"low"`/`"high"` here. Default: SDK/Claude Code default |
135
149
  | `systemPrompt` | string \| object | No | Override the agent's system prompt. Default: SDK/Claude Code default. Pass a string for full replacement, or `{ type: "preset", preset: "claude_code", append?: "..." }` to extend the default prompt |
136
150
  | `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` (server-clamped to 5min) |
137
151
  | `advanced` | object | No | Advanced/low-frequency parameters (see below) |
@@ -139,32 +153,32 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
139
153
  <details>
140
154
  <summary><code>advanced</code> object parameters (24 low-frequency parameters)</summary>
141
155
 
142
- | Parameter | Type | Description |
143
- | ------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
144
- | `advanced.tools` | string[] \| object | Define the base tool set. Default: SDK/Claude Code default toolset. Array of tool name strings, or `{ type: "preset", preset: "claude_code" }` for the default toolset. `allowedTools`/`disallowedTools` further filter on top of this |
145
- | `advanced.persistSession` | boolean | Persist session history to disk (`~/.claude/projects/`). Default: `true`. Set `false` to disable. |
146
- | `advanced.sessionInitTimeoutMs` | number | Session init timeout in milliseconds waiting for `system/init`. Default: `10000`. |
147
- | `advanced.agents` | object | Define custom sub-agents the main agent can delegate tasks to. Default: none. SDK default: if a sub-agent omits `tools`, it inherits all tools from the parent. |
148
- | `advanced.agent` | string | Name of a custom agent (defined in `agents`) to use as the primary agent. Default: omitted |
149
- | `advanced.maxBudgetUsd` | number | Maximum budget in USD. Default: SDK/Claude Code default |
150
- | `advanced.betas` | string[] | Beta features (e.g. `["context-1m-2025-08-07"]`). Default: none |
151
- | `advanced.additionalDirectories` | string[] | Additional directories the agent can access beyond cwd. Default: none |
152
- | `advanced.outputFormat` | object | Structured output: `{ type: "json_schema", schema: {...} }`. Default: omitted (plain text) |
153
- | `advanced.pathToClaudeCodeExecutable` | string | Path to the Claude Code executable. Default: SDK-bundled Claude Code (cli.js) |
154
- | `advanced.mcpServers` | object | MCP server configurations (key: server name, value: server config). Default: none |
155
- | `advanced.sandbox` | object | Sandbox configuration for isolating shell command execution (e.g., Docker container settings). Default: SDK/Claude Code default |
156
- | `advanced.fallbackModel` | string | Fallback model if the primary model fails or is unavailable. Default: none |
157
- | `advanced.enableFileCheckpointing` | boolean | Enable file checkpointing to track file changes during the session. Default: `false` |
158
- | `advanced.toolConfig` | object | Per-tool built-in configuration. Example: `{ askUserQuestion: { previewFormat: "html" } }`. Default: none |
159
- | `advanced.includePartialMessages` | boolean | When true, includes intermediate streaming messages in the response. Useful for real-time progress monitoring. Default: false |
160
- | `advanced.promptSuggestions` | boolean | When true, emits post-turn prompt suggestion events (`prompt_suggestion`). Default: `false` |
161
- | `advanced.agentProgressSummaries` | boolean | When true, emits AI-generated summaries on `system/task_progress` events for running subagents. Default: `false` |
162
- | `advanced.strictMcpConfig` | boolean | Enforce strict validation of MCP server configurations. Default: `false` |
163
- | `advanced.settings` | string \| object | Extra Claude Code flag settings. Pass either a path to a settings JSON file or an inline settings object. Default: none |
164
- | `advanced.settingSources` | string[] | Which filesystem settings to load. Defaults to `["user", "project", "local"]` (loads all settings and CLAUDE.md). Pass `[]` for SDK isolation mode |
165
- | `advanced.debug` | boolean | Enable debug mode for verbose logging. Default: `false` |
166
- | `advanced.debugFile` | string | Write debug logs to a specific file path (implicitly enables debug mode). Default: omitted |
167
- | `advanced.env` | object | Environment variables to merge with process.env and pass to the Claude Code process (user values take precedence). Default: inherit process.env |
156
+ | Parameter | Type | Description |
157
+ | ------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
158
+ | `advanced.tools` | string[] \| object | Visible built-in tool set. Array of exact tool names, `[]` to disable built-ins, or `{ type: "preset", preset: "claude_code" }` for the default set. This controls what Claude can see/call; `allowedTools` only controls pre-approval. |
159
+ | `advanced.persistSession` | boolean | Persist session history to disk (`~/.claude/projects/`). Default: `true`. Set `false` to disable. |
160
+ | `advanced.sessionInitTimeoutMs` | number | Session init timeout in milliseconds waiting for `system/init`. Default: `10000`. |
161
+ | `advanced.agents` | object | Define custom sub-agents the main agent can delegate tasks to. Default: none. SDK default: if a sub-agent omits `tools`, it inherits all tools from the parent. |
162
+ | `advanced.agent` | string | Name of a custom agent (defined in `agents`) to use as the primary agent. Default: omitted |
163
+ | `advanced.maxBudgetUsd` | number | Maximum budget in USD. Default: SDK/Claude Code default |
164
+ | `advanced.betas` | string[] | Beta features (e.g. `["context-1m-2025-08-07"]`). Default: none |
165
+ | `advanced.additionalDirectories` | string[] | Additional directories the agent can access beyond cwd. Default: none |
166
+ | `advanced.outputFormat` | object | Structured output config: `{ type: "json_schema", schema: {...} }`. Default: omitted (plain text) |
167
+ | `advanced.pathToClaudeCodeExecutable` | string | Path to the Claude Code executable. Default: auto-detect `claude`, then `claude-internal`, else SDK-bundled Claude Code (cli.js). |
168
+ | `advanced.mcpServers` | object | MCP server configurations keyed by server name. Default: none |
169
+ | `advanced.sandbox` | object | Sandbox behavior config object. This controls sandbox behavior, not the actual Read/Edit/WebFetch permission rules. Default: SDK/Claude Code default |
170
+ | `advanced.fallbackModel` | string | Fallback model if the primary model fails or is unavailable. Default: none |
171
+ | `advanced.enableFileCheckpointing` | boolean | Enable file checkpointing to track file changes during the session. Default: `false` |
172
+ | `advanced.toolConfig` | object | Per-tool built-in configuration. Example: `{ askUserQuestion: { previewFormat: "html" } }`. Default: none |
173
+ | `advanced.includePartialMessages` | boolean | When true, includes intermediate streaming messages in the response. Useful for real-time progress monitoring. Default: false |
174
+ | `advanced.promptSuggestions` | boolean | When true, emits post-turn prompt suggestion events (`prompt_suggestion`). Default: `false` |
175
+ | `advanced.agentProgressSummaries` | boolean | When true, emits AI-generated summaries on `system/task_progress` events for running subagents. Default: `false` |
176
+ | `advanced.strictMcpConfig` | boolean | Enforce strict validation of MCP server configurations. Default: `false` |
177
+ | `advanced.settings` | string \| object | Extra Claude Code flag settings. Pass either a path to a settings JSON file or an inline settings object. These load at the highest-priority flag-settings layer. Default: none |
178
+ | `advanced.settingSources` | string[] | Which filesystem settings to load. Defaults to `["user", "project", "local"]` (loads all settings and CLAUDE.md). Pass `[]` for SDK isolation mode |
179
+ | `advanced.debug` | boolean | Enable debug mode for verbose logging. Default: `false` |
180
+ | `advanced.debugFile` | string | Write debug logs to a specific file path (implicitly enables debug mode). Default: omitted |
181
+ | `advanced.env` | object | Environment variables merged over `process.env` before launching Claude Code (user values take precedence). Default: inherit `process.env` |
168
182
 
169
183
  </details>
170
184
 
@@ -174,6 +188,8 @@ Notes:
174
188
 
175
189
  - `resumeToken` is omitted by default, and is only returned when `CLAUDE_CODE_MCP_RESUME_SECRET` is set on the server.
176
190
  - On error: `{ sessionId: "", status: "error", error }`
191
+ - `model` is optional. If omitted, Claude Code chooses the effective model from its own defaults/settings; inspect session/result metadata if you need to know what actually ran.
192
+ - If you plan to continue with `claude_code_reply`, keep the session persistent (`advanced.persistSession=true`, which is already the default).
177
193
 
178
194
  Use `claude_code_check` to poll events and obtain the final `result`.
179
195
 
@@ -189,56 +205,58 @@ Use `claude_code_check` to poll events and obtain the final `result`.
189
205
 
190
206
  Continue an existing session by sending a follow-up message. The agent retains full context from previous turns including files read, code analysis, and conversation history.
191
207
 
192
- | Parameter | Type | Required | Description |
193
- | ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
194
- | `sessionId` | string | Yes | Session ID from a previous `claude_code` call |
195
- | `prompt` | string | Yes | Follow-up prompt |
196
- | `forkSession` | boolean | No | Create a branched copy of this session. Default: `false` |
197
- | `effort` | string | No | Effort level override for this run (and for future replies when not forking). Default: SDK/Claude Code default |
198
- | `thinking` | object | No | Thinking mode override for this run (and for future replies when not forking). Default: SDK/Claude Code default |
199
- | `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` (server-clamped to 5min) |
200
- | `sessionInitTimeoutMs` | number | No | Fork init timeout in milliseconds (only when `forkSession=true`). Default: `10000` |
201
- | `diskResumeConfig` | object | No | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing |
208
+ Important protocol note: prefer `claude_code_reply` over starting a fresh `claude_code` session when you want to continue the same work. This requires a persistent in-memory session, or `diskResumeConfig` when disk resume fallback is enabled.
209
+
210
+ | Parameter | Type | Required | Description |
211
+ | ---------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
212
+ | `sessionId` | string | Yes | Session ID from a previous `claude_code` call |
213
+ | `prompt` | string | Yes | Follow-up prompt |
214
+ | `forkSession` | boolean | No | Create a branched copy of this session. Default: `false` |
215
+ | `effort` | string | No | Effort string override for this run (and for future replies when not forking): `"low"`, `"medium"`, `"high"`, `"max"`. Default: SDK/Claude Code default |
216
+ | `thinking` | object | No | Thinking config object override for this run (and for future replies when not forking): `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens?: N }`, or `{ type: "disabled" }`. Default: SDK/Claude Code default |
217
+ | `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` (server-clamped to 5min) |
218
+ | `sessionInitTimeoutMs` | number | No | Fork init timeout in milliseconds (only when `forkSession=true`). Default: `10000` |
219
+ | `diskResumeConfig` | object | No | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing |
202
220
 
203
221
  <details>
204
222
  <summary><code>diskResumeConfig</code> object parameters (34 disk-resume-only parameters)</summary>
205
223
 
206
- | Parameter | Type | Description |
207
- | --------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------------------- |
208
- | `diskResumeConfig.resumeToken` | string | Resume token returned by `claude_code` / `claude_code_reply`. Required for disk resume fallback |
209
- | `diskResumeConfig.cwd` | string | Working directory. Required for disk resume. |
210
- | `diskResumeConfig.allowedTools` | string[] | Auto-approved tool names (see `claude_code`). Default: `[]` |
211
- | `diskResumeConfig.disallowedTools` | string[] | Forbidden tool names (see `claude_code`). Default: `[]` |
212
- | `diskResumeConfig.strictAllowedTools` | boolean | Enforce strict allow-list behavior for `allowedTools`. Default: `false` |
213
- | `diskResumeConfig.tools` | string[] \| object | Base tool set (see `claude_code`). Default: SDK/Claude Code default |
214
- | `diskResumeConfig.persistSession` | boolean | Persist session history to disk. Default: `true` |
215
- | `diskResumeConfig.maxTurns` | number | Maximum number of agent reasoning steps. Default: SDK/Claude Code default |
216
- | `diskResumeConfig.model` | string | Model to use. Default: SDK/Claude Code default |
217
- | `diskResumeConfig.systemPrompt` | string \| object | Override the agent's system prompt. Default: SDK/Claude Code default |
218
- | `diskResumeConfig.agents` | object | Custom sub-agent definitions (see `claude_code`). Default: none |
219
- | `diskResumeConfig.agent` | string | Primary agent name (see `claude_code` tool). Default: omitted |
220
- | `diskResumeConfig.maxBudgetUsd` | number | Maximum budget in USD. Default: SDK/Claude Code default |
221
- | `diskResumeConfig.effort` | string | Effort level. Default: SDK/Claude Code default |
222
- | `diskResumeConfig.betas` | string[] | Beta features. Default: none |
223
- | `diskResumeConfig.additionalDirectories` | string[] | Additional directories. Default: none |
224
- | `diskResumeConfig.outputFormat` | object | Structured output format. Default: omitted (plain text) |
225
- | `diskResumeConfig.thinking` | object | Thinking mode. Default: SDK/Claude Code default |
226
- | `diskResumeConfig.resumeSessionAt` | string | Resume only up to and including a specific message UUID. Default: omitted |
227
- | `diskResumeConfig.pathToClaudeCodeExecutable` | string | Path to Claude Code executable. Default: SDK-bundled Claude Code (cli.js) |
228
- | `diskResumeConfig.mcpServers` | object | MCP server configurations. Default: none |
229
- | `diskResumeConfig.sandbox` | object | Sandbox config for command isolation. Default: SDK/Claude Code default |
230
- | `diskResumeConfig.fallbackModel` | string | Fallback model. Default: none |
231
- | `diskResumeConfig.enableFileCheckpointing` | boolean | Enable file checkpointing. Default: `false` |
232
- | `diskResumeConfig.toolConfig` | object | Per-tool built-in configuration. Default: none |
233
- | `diskResumeConfig.includePartialMessages` | boolean | Include intermediate streaming messages. Default: `false` |
234
- | `diskResumeConfig.promptSuggestions` | boolean | Emit post-turn prompt suggestion events (`prompt_suggestion`). Default: `false` |
235
- | `diskResumeConfig.agentProgressSummaries` | boolean | Emit AI-generated subagent progress summaries. Default: `false` |
236
- | `diskResumeConfig.strictMcpConfig` | boolean | Strict MCP config validation. Default: `false` |
237
- | `diskResumeConfig.settings` | string \| object | Extra Claude Code flag settings (path or inline object). Default: none |
238
- | `diskResumeConfig.settingSources` | string[] | Which filesystem settings to load. Default: `["user", "project", "local"]` |
239
- | `diskResumeConfig.debug` | boolean | Debug mode. Default: `false` |
240
- | `diskResumeConfig.debugFile` | string | Debug log file path. Default: omitted |
241
- | `diskResumeConfig.env` | object | Environment variables. Default: inherit process.env (user values override) |
224
+ | Parameter | Type | Description |
225
+ | --------------------------------------------- | ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
226
+ | `diskResumeConfig.resumeToken` | string | Resume token returned by `claude_code` / `claude_code_reply`. Required for disk resume fallback |
227
+ | `diskResumeConfig.cwd` | string | Working directory. Required for disk resume. |
228
+ | `diskResumeConfig.allowedTools` | string[] | Auto-approved tool names (see `claude_code`). Default: `[]` |
229
+ | `diskResumeConfig.disallowedTools` | string[] | Forbidden tool names (see `claude_code`). Default: `[]` |
230
+ | `diskResumeConfig.strictAllowedTools` | boolean | Server-side strict allow-list behavior for `allowedTools`. Default: `false` |
231
+ | `diskResumeConfig.tools` | string[] \| object | Base tool set (see `claude_code`). Default: SDK/Claude Code default |
232
+ | `diskResumeConfig.persistSession` | boolean | Persist session history to disk. Default: `true` |
233
+ | `diskResumeConfig.maxTurns` | number | Maximum number of agent reasoning steps. Default: SDK/Claude Code default |
234
+ | `diskResumeConfig.model` | string | Model to use. Default: SDK/Claude Code default |
235
+ | `diskResumeConfig.systemPrompt` | string \| object | Override the agent's system prompt. Default: SDK/Claude Code default |
236
+ | `diskResumeConfig.agents` | object | Custom sub-agent definitions (see `claude_code`). Default: none |
237
+ | `diskResumeConfig.agent` | string | Primary agent name (see `claude_code` tool). Default: omitted |
238
+ | `diskResumeConfig.maxBudgetUsd` | number | Maximum budget in USD. Default: SDK/Claude Code default |
239
+ | `diskResumeConfig.effort` | string | Effort level. Default: SDK/Claude Code default |
240
+ | `diskResumeConfig.betas` | string[] | Beta features. Default: none |
241
+ | `diskResumeConfig.additionalDirectories` | string[] | Additional directories. Default: none |
242
+ | `diskResumeConfig.outputFormat` | object | Structured output config. Default: omitted (plain text) |
243
+ | `diskResumeConfig.thinking` | object | Thinking config object: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens?: N }`, or `{ type: "disabled" }`. Default: SDK/Claude Code default |
244
+ | `diskResumeConfig.resumeSessionAt` | string | Resume only up to and including a specific message UUID. Default: omitted |
245
+ | `diskResumeConfig.pathToClaudeCodeExecutable` | string | Path to Claude Code executable. Default: auto-detect `claude`, then `claude-internal`, else SDK-bundled Claude Code (cli.js) |
246
+ | `diskResumeConfig.mcpServers` | object | MCP server configurations keyed by server name. Default: none |
247
+ | `diskResumeConfig.sandbox` | object | Sandbox behavior config object. Default: SDK/Claude Code default |
248
+ | `diskResumeConfig.fallbackModel` | string | Fallback model. Default: none |
249
+ | `diskResumeConfig.enableFileCheckpointing` | boolean | Enable file checkpointing. Default: `false` |
250
+ | `diskResumeConfig.toolConfig` | object | Per-tool built-in configuration. Default: none |
251
+ | `diskResumeConfig.includePartialMessages` | boolean | Include intermediate streaming messages. Default: `false` |
252
+ | `diskResumeConfig.promptSuggestions` | boolean | Emit post-turn prompt suggestion events (`prompt_suggestion`). Default: `false` |
253
+ | `diskResumeConfig.agentProgressSummaries` | boolean | Emit AI-generated subagent progress summaries. Default: `false` |
254
+ | `diskResumeConfig.strictMcpConfig` | boolean | Strict MCP config validation. Default: `false` |
255
+ | `diskResumeConfig.settings` | string \| object | Extra Claude Code flag settings (path or inline object), loaded at the highest-priority flag-settings layer. Default: none |
256
+ | `diskResumeConfig.settingSources` | string[] | Which filesystem settings to load. Default: `["user", "project", "local"]` |
257
+ | `diskResumeConfig.debug` | boolean | Debug mode. Default: `false` |
258
+ | `diskResumeConfig.debugFile` | string | Debug log file path (implicitly enables debug). Default: omitted |
259
+ | `diskResumeConfig.env` | object | Environment variables merged over `process.env` (user values override). Default: inherit process.env |
242
260
 
243
261
  </details>
244
262
 
@@ -254,10 +272,12 @@ Use `claude_code_check` to poll events and obtain the final `result`.
254
272
  Gotchas:
255
273
 
256
274
  - Permission approvals have a timeout (default 60s via `permissionRequestTimeoutMs`) and will auto-deny; watch `actions[].expiresAt` / `actions[].remainingMs`.
275
+ - `claude_code_reply` requires a persistent session or an enabled disk-resume setup; one-shot/non-persistent sessions cannot be resumed later.
257
276
  - `Read` has a per-call size cap in practice (often ~256KB); for large files use `offset`/`limit` or chunk with `Grep`.
258
277
  - `Edit` with `replace_all=true` is substring replacement; if no match is found the tool returns a clear error.
259
278
  - On Windows, this server normalizes common MSYS-style paths (e.g. `/d/...`, `/mnt/c/...`, `/cygdrive/c/...`, `//server/share/...`) for `cwd`, `additionalDirectories`, and tool inputs that include `file_path`.
260
279
  - On Windows, POSIX home paths like `/home/user/...` are **not** rewritten to drive paths; prefer absolute Windows paths under your current `cwd` to avoid out-of-bounds permission prompts.
280
+ - On Windows, Claude Code itself needs Git Bash; set `CLAUDE_CODE_GIT_BASH_PATH` in your MCP client config if auto-detection is unreliable.
261
281
  - `TeamDelete` may require members to reach `shutdown_approved` (otherwise you may see "active member" errors); cleanup can be asynchronous during shutdown.
262
282
  - Skills may become available later in the same session (early calls may show "Unknown", later succeed after skills are loaded/registered).
263
283
  - `toolCatalogCount` and `availableTools` are different views: catalog is server-known tools, while `availableTools` comes from each session's runtime `system/init.tools`.
@@ -300,6 +320,8 @@ List, inspect, cancel, or interrupt sessions.
300
320
 
301
321
  Poll session events/results and approve/deny pending permission requests.
302
322
 
323
+ Important protocol note: `action="poll"` is the main loop, and `action="respond_permission"` is the only interactive approval flow on this backend. `respond_user_input` is not supported.
324
+
303
325
  | Parameter | Type | Required | Description |
304
326
  | ------------------- | ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
305
327
  | `action` | string | Yes | `"poll"` or `"respond_permission"` |
@@ -498,15 +520,24 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
498
520
 
499
521
  All environment variables are optional. They are set on the MCP server process (not on the Claude Code child process — for that, use the `env` tool parameter).
500
522
 
501
- | Variable | Description | Default |
502
- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------- |
503
- | `CLAUDE_CODE_GIT_BASH_PATH` | Path to `bash.exe` on Windows (see [Windows Support](#windows-support)) | Auto-detected |
504
- | `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME` | Set to `1` to allow `claude_code_reply` to resume from on-disk transcripts when the in-memory session is missing | `0` (disabled) |
505
- | `CLAUDE_CODE_MCP_RESUME_SECRET` | HMAC secret used to validate `resumeToken` for disk resume fallback (recommended if disk resume is enabled) | _(unset)_ |
506
- | `CLAUDE_CODE_MCP_MAX_SESSIONS` | Maximum number of in-memory sessions (set `0` to disable the limit) | `128` |
507
- | `CLAUDE_CODE_MCP_MAX_PENDING_PERMISSIONS` | Maximum number of outstanding permission requests per session (set `0` to disable the limit) | `64` |
508
- | `CLAUDE_CODE_MCP_EVENT_BUFFER_MAX_SIZE` | Soft limit for in-memory event buffer per session (`0` is not supported) | `1000` |
509
- | `CLAUDE_CODE_MCP_EVENT_BUFFER_HARD_MAX_SIZE` | Hard limit for in-memory event buffer per session (clamped to be `>= max`; `0` is not supported) | `2000` |
523
+ | Variable | Description | Default |
524
+ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------- |
525
+ | `CLAUDE_CODE_GIT_BASH_PATH` | Path to `bash.exe` on Windows (see [Windows Support](#windows-support)) | Auto-detected |
526
+ | `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND` | Exact command name to resolve from `PATH` as the default Claude executable (for example `claude` or `claude-internal`). Mutually exclusive with `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` | _(unset)_ |
527
+ | `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` | Explicit filesystem path to use as the default Claude executable. Mutually exclusive with `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND` | _(unset)_ |
528
+ | `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME` | Set to `1` to allow `claude_code_reply` to resume from on-disk transcripts when the in-memory session is missing | `0` (disabled) |
529
+ | `CLAUDE_CODE_MCP_RESUME_SECRET` | HMAC secret used to validate `resumeToken` for disk resume fallback (recommended if disk resume is enabled) | _(unset)_ |
530
+ | `CLAUDE_CODE_MCP_MAX_SESSIONS` | Maximum number of in-memory sessions (set `0` to disable the limit) | `128` |
531
+ | `CLAUDE_CODE_MCP_MAX_PENDING_PERMISSIONS` | Maximum number of outstanding permission requests per session (set `0` to disable the limit) | `64` |
532
+ | `CLAUDE_CODE_MCP_EVENT_BUFFER_MAX_SIZE` | Soft limit for in-memory event buffer per session (`0` is not supported) | `1000` |
533
+ | `CLAUDE_CODE_MCP_EVENT_BUFFER_HARD_MAX_SIZE` | Hard limit for in-memory event buffer per session (clamped to be `>= max`; `0` is not supported) | `2000` |
534
+
535
+ ### Choosing the default Claude executable
536
+
537
+ - `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_PATH` and `CLAUDE_CODE_MCP_DEFAULT_CLAUDE_COMMAND` are mutually exclusive.
538
+ - If neither is set, the server auto-detects `claude`, then `claude-internal`, then falls back to the SDK-bundled CLI.
539
+ - Request-level `pathToClaudeCodeExecutable` still overrides these server defaults.
540
+ - Invalid values for these env vars are treated as startup misconfiguration and will fail the server fast.
510
541
 
511
542
  ### How to configure
512
543