@leo000001/claude-code-mcp 2.2.0 → 2.4.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 (7) hide show
  1. package/CHANGELOG.md +29 -1
  2. package/CONTRIBUTING.md +7 -0
  3. package/README.md +80 -66
  4. package/dist/index.js +1224 -187
  5. package/dist/index.js.map +1 -1
  6. package/package.json +1 -3
  7. package/dist/index.d.ts +0 -2
package/CHANGELOG.md CHANGED
@@ -2,6 +2,33 @@
2
2
 
3
3
  ## Unreleased
4
4
 
5
+ ### Security
6
+
7
+ - Validate `resumeToken` using timing-safe comparison (`timingSafeEqual` for fixed-length HMAC tokens) to reduce timing side-channel risk.
8
+
9
+ ### Improvements
10
+
11
+ - Session cleanup now marks timed-out running/waiting sessions as `cancelled` for consistent status semantics.
12
+ - `SessionManager.destroy()` now clears in-memory session/runtime maps after aborting active runs, so post-destroy reads are no longer stale.
13
+ - Event buffer eviction now uses batch compaction (instead of repeated `findIndex` + `splice`) and `readEvents` now uses binary search for cursor start.
14
+ - Add configurable event-buffer limits via `CLAUDE_CODE_MCP_EVENT_BUFFER_MAX_SIZE` and `CLAUDE_CODE_MCP_EVENT_BUFFER_HARD_MAX_SIZE`.
15
+ - Runtime tool-discovery updates now notify both tools and resources (internal-tools resource change notification).
16
+ - Enrich compatibility resources with package version, disk-resume diagnostics, and runtime limits.
17
+ - Remove deprecated `claude_code` parameter aliases: top-level `sessionInitTimeoutMs` and `advanced.effort` / `advanced.thinking`.
18
+
19
+ ### Documentation
20
+
21
+ - Align README/DESIGN/AGENTS with current defaults and behavior (timeout clamp, advanced parameter count, lifecycle semantics).
22
+ - Clarify package positioning as CLI-first and remove stale guidance that implied a public programmatic API surface.
23
+ - Update CONTRIBUTING with local environment requirements (Node/npm and Windows Git Bash notes).
24
+
25
+ ### Tests
26
+
27
+ - Add dedicated tests for `resume-token` and `claude-code-reply`.
28
+ - Extend tests for event-buffer behavior, resource metadata, and runtime resource notifications.
29
+
30
+ ## 2.2.0 (2026-02-17)
31
+
5
32
  ### Improvements
6
33
 
7
34
  - Add `CLAUDE_CODE_MCP_MAX_SESSIONS` (default: `128`) to cap in-memory session count and reduce risk of memory exhaustion.
@@ -60,8 +87,9 @@
60
87
  - `claude_code` and `claude_code_reply` now start asynchronously and return `{ sessionId, status: "running", pollInterval }`. Use `claude_code_check` to poll events and fetch the final `result`.
61
88
  - Removed tool: `claude_code_configure`
62
89
  - New tool: `claude_code_check` (poll + respond_permission)
90
+ - Legacy `bypassPermissions` mode is no longer exposed in MCP schemas for 2.x.
63
91
  - **Parameter nesting refactor**: low-frequency parameters have been folded into nested objects to reduce top-level clutter. This is a breaking change for callers that pass these parameters at the top level:
64
- - `claude_code`: 22 low-frequency params moved into `advanced` object (e.g. `effort` → `advanced.effort`, `tools` → `advanced.tools`, `agents` → `advanced.agents`, `env` → `advanced.env`)
92
+ - `claude_code`: 22 low-frequency params moved into `advanced` object in 2.0.0 (including `advanced.effort` / `advanced.thinking`, later removed)
65
93
  - `claude_code_reply`: 28 disk-resume params moved into `diskResumeConfig` object (e.g. `resumeToken` → `diskResumeConfig.resumeToken`, `cwd` → `diskResumeConfig.cwd`)
66
94
  - `claude_code_check`: 9 poll control params moved into `pollOptions` object (e.g. `includeTools` → `pollOptions.includeTools`); 2 permission response params moved into `permissionOptions` object (e.g. `updatedInput` → `permissionOptions.updatedInput`)
67
95
 
package/CONTRIBUTING.md CHANGED
@@ -10,6 +10,13 @@ cd claude-code-mcp
10
10
  npm install
11
11
  ```
12
12
 
13
+ ### Local Environment Requirements
14
+
15
+ - Node.js `>=18` (Node 20/22 recommended for local development)
16
+ - npm (bundled with Node)
17
+ - Windows contributors: install **Git for Windows** (`bash.exe`) for Claude Code CLI compatibility
18
+ - Optional: set `CLAUDE_CODE_GIT_BASH_PATH` explicitly when testing MCP clients launched outside your terminal environment
19
+
13
20
  ## Development Workflow
14
21
 
15
22
  1. Create a feature branch from the default branch
package/README.md CHANGED
@@ -8,6 +8,8 @@ MCP server that wraps [Claude Code (Claude Agent SDK)](https://docs.anthropic.co
8
8
 
9
9
  Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sdk/) design philosophy — minimum tools, maximum capability.
10
10
 
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
+
11
13
  ## Features
12
14
 
13
15
  - **4 tools** covering the full agent lifecycle: start, continue, check/poll, manage
@@ -60,7 +62,7 @@ Add to your MCP client configuration (Claude Desktop, Cursor, etc.):
60
62
  }
61
63
  ```
62
64
 
63
- > Some clients cache tool definitions at connect-time. This server emits `notifications/tools/list_changed` after runtime tool discovery so clients can refresh the `claude_code` tool description.
65
+ > Some clients cache tool/resource metadata at connect-time. This server emits `notifications/tools/list_changed` and resource update notifications after runtime tool discovery so clients can refresh both the `claude_code` tool description and `internal-tools` resource.
64
66
 
65
67
  ### Anthropic Claude Code CLI (as an MCP client)
66
68
 
@@ -77,7 +79,7 @@ codex mcp add claude-code -- npx -y @leo000001/claude-code-mcp
77
79
  Or manually add to `~/.codex/config.toml`:
78
80
 
79
81
  ```toml
80
- [mcp_servers.claude-code]
82
+ [mcp_servers.claude-code-mcp]
81
83
  command = "npx"
82
84
  args = ["-y", "@leo000001/claude-code-mcp"]
83
85
  ```
@@ -108,11 +110,10 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
108
110
  | `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 |
109
111
  | `maxTurns` | number | No | Maximum number of agent reasoning steps. Each step may involve one or more tool calls. Default: SDK/Claude Code default |
110
112
  | `model` | string | No | Model to use (e.g. `"claude-sonnet-4-5-20250929"`). Default: SDK/Claude Code default |
111
- | `effort` | string | No | Effort level: `"low"`, `"medium"`, `"high"`, `"max"`. Default: SDK/Claude Code default |
112
- | `thinking` | object | No | Thinking mode: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens: N }`, or `{ type: "disabled" }`. Default: SDK/Claude Code default |
113
+ | `effort` | string | No | Effort level: `"low"`, `"medium"`, `"high"`, `"max"`. Default: SDK/Claude Code default |
114
+ | `thinking` | object | No | Thinking mode: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens: N }`, or `{ type: "disabled" }`. Default: SDK/Claude Code default |
113
115
  | `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 |
114
- | `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` (server-clamped to 5min) |
115
- | `sessionInitTimeoutMs` | number | No | **Compatibility alias** for `advanced.sessionInitTimeoutMs` (deprecated for `claude_code`). Default: `10000`. If both are provided, `advanced.sessionInitTimeoutMs` wins |
116
+ | `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` (server-clamped to 5min) |
116
117
  | `advanced` | object | No | Advanced/low-frequency parameters (see below) |
117
118
 
118
119
  <details>
@@ -122,7 +123,7 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
122
123
  | ------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
123
124
  | `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 |
124
125
  | `advanced.persistSession` | boolean | Persist session history to disk (`~/.claude/projects/`). Default: `true`. Set `false` to disable. |
125
- | `advanced.sessionInitTimeoutMs` | number | Session init timeout in milliseconds waiting for `system/init`. Default: `10000`. **Recommended location for `claude_code` callers.** |
126
+ | `advanced.sessionInitTimeoutMs` | number | Session init timeout in milliseconds waiting for `system/init`. Default: `10000`. |
126
127
  | `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. |
127
128
  | `advanced.agent` | string | Name of a custom agent (defined in `agents`) to use as the primary agent. Default: omitted |
128
129
  | `advanced.maxBudgetUsd` | number | Maximum budget in USD. Default: SDK/Claude Code default |
@@ -141,8 +142,6 @@ Start a new Claude Code session. The agent autonomously performs coding tasks: r
141
142
  | `advanced.debugFile` | string | Write debug logs to a specific file path (implicitly enables debug mode). Default: omitted |
142
143
  | `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 |
143
144
 
144
- Deprecated aliases: `advanced.effort` and `advanced.thinking` are still accepted for compatibility, but prefer top-level `effort` / `thinking` (top-level wins if both are set).
145
-
146
145
  </details>
147
146
 
148
147
  **Returns:** `{ sessionId, status: "running", pollInterval, resumeToken? }`
@@ -151,7 +150,6 @@ Notes:
151
150
 
152
151
  - `resumeToken` is omitted by default, and is only returned when `CLAUDE_CODE_MCP_RESUME_SECRET` is set on the server.
153
152
  - On error: `{ sessionId: "", status: "error", error }`
154
- - If `sessionInitTimeoutMs` (top-level alias) is used, `claude_code` may return `compatWarnings` to guide migration to `advanced.sessionInitTimeoutMs`.
155
153
 
156
154
  Use `claude_code_check` to poll events and obtain the final `result`.
157
155
 
@@ -167,16 +165,16 @@ Use `claude_code_check` to poll events and obtain the final `result`.
167
165
 
168
166
  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.
169
167
 
170
- | Parameter | Type | Required | Description |
171
- | ---------------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------- |
172
- | `sessionId` | string | Yes | Session ID from a previous `claude_code` call |
173
- | `prompt` | string | Yes | Follow-up prompt |
174
- | `forkSession` | boolean | No | Create a branched copy of this session. Default: `false` |
175
- | `effort` | string | No | Effort level override for this run (and for future replies when not forking). Default: SDK/Claude Code default |
176
- | `thinking` | object | No | Thinking mode override for this run (and for future replies when not forking). Default: SDK/Claude Code default |
177
- | `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` |
178
- | `sessionInitTimeoutMs` | number | No | Fork init timeout in milliseconds (only when `forkSession=true`). Default: `10000` |
179
- | `diskResumeConfig` | object | No | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing |
168
+ | Parameter | Type | Required | Description |
169
+ | ---------------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
170
+ | `sessionId` | string | Yes | Session ID from a previous `claude_code` call |
171
+ | `prompt` | string | Yes | Follow-up prompt |
172
+ | `forkSession` | boolean | No | Create a branched copy of this session. Default: `false` |
173
+ | `effort` | string | No | Effort level override for this run (and for future replies when not forking). Default: SDK/Claude Code default |
174
+ | `thinking` | object | No | Thinking mode override for this run (and for future replies when not forking). Default: SDK/Claude Code default |
175
+ | `permissionRequestTimeoutMs` | number | No | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` (server-clamped to 5min) |
176
+ | `sessionInitTimeoutMs` | number | No | Fork init timeout in milliseconds (only when `forkSession=true`). Default: `10000` |
177
+ | `diskResumeConfig` | object | No | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing |
180
178
 
181
179
  <details>
182
180
  <summary><code>diskResumeConfig</code> object parameters (28 disk-resume-only parameters)</summary>
@@ -233,48 +231,59 @@ Gotchas:
233
231
  - 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.
234
232
  - `TeamDelete` may require members to reach `shutdown_approved` (otherwise you may see "active member" errors); cleanup can be asynchronous during shutdown.
235
233
  - Skills may become available later in the same session (early calls may show "Unknown", later succeed after skills are loaded/registered).
234
+ - `toolCatalogCount` and `availableTools` are different views: catalog is server-known tools, while `availableTools` comes from each session's runtime `system/init.tools`.
236
235
  - Some internal features (e.g. ToolSearch) may not appear in `availableTools` (derived from SDK `system/init.tools`).
237
236
 
238
237
  ### Resources
239
238
 
240
239
  If your MCP client supports resources, this server exposes a couple of **read-only** MCP resources:
241
240
 
242
- - `claude-code-mcp:///server-info` (JSON): server metadata (version/platform/runtime)
243
- - `claude-code-mcp:///internal-tools` (JSON): internal tool catalog (runtime-aware)
241
+ - `claude-code-mcp:///server-info` (JSON): server metadata (version/platform/runtime + capabilities/limits)
242
+ - `claude-code-mcp:///internal-tools` (JSON): internal tool catalog (runtime-aware, includes permission/schema metadata)
244
243
  - `claude-code-mcp:///gotchas` (Markdown): practical limits/gotchas
245
- - `claude-code-mcp:///compat-report` (JSON): compatibility report (transport/platform assumptions, runtime warnings, guidance)
244
+ - `claude-code-mcp:///quickstart` (Markdown): minimal async start/poll/respond flow
245
+ - `claude-code-mcp:///errors` (JSON): structured error-code catalog and remediation hints
246
+ - `claude-code-mcp:///compat-report` (JSON): compatibility report (transport/platform assumptions, runtime warnings, guidance, recommended settings, tool count diagnostics)
247
+
248
+ Resource templates:
249
+
250
+ - `claude-code-mcp:///session/{sessionId}`: lightweight session snapshot for a specific session
251
+ - `claude-code-mcp:///tools/runtime{?sessionId}`: runtime tool view globally or per session
252
+ - `claude-code-mcp:///compat/diff{?client}`: client-specific compatibility guidance
246
253
 
247
254
  **Disk resume (optional):** By default, `claude_code_reply` requires the session to exist in the MCP server's in-memory Session Manager. If you set `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1`, it can attempt to resume using the Claude Code CLI's on-disk transcript even when the in-memory session is missing (e.g. after a restart / TTL cleanup). For safety, disk resume fallback requires `CLAUDE_CODE_MCP_RESUME_SECRET` to be set on the server and requires callers to pass `diskResumeConfig.resumeToken` (returned by `claude_code` / `claude_code_reply` when `CLAUDE_CODE_MCP_RESUME_SECRET` is set).
248
255
 
249
256
  ### `claude_code_session` — Manage sessions
250
257
 
251
- List, inspect, or cancel sessions.
258
+ List, inspect, cancel, or interrupt sessions.
252
259
 
253
- | Parameter | Type | Required | Description |
254
- | ------------------ | ------- | -------------- | ------------------------------------------------------------------------------ |
255
- | `action` | string | Yes | `"list"`, `"get"`, or `"cancel"` |
256
- | `sessionId` | string | For get/cancel | Target session ID |
257
- | `includeSensitive` | boolean | No | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories` (default: false) |
260
+ | Parameter | Type | Required | Description |
261
+ | ------------------ | ------- | ------------------------ | ------------------------------------------------------------------------------ |
262
+ | `action` | string | Yes | `"list"`, `"get"`, `"cancel"`, or `"interrupt"` |
263
+ | `sessionId` | string | For get/cancel/interrupt | Target session ID |
264
+ | `includeSensitive` | boolean | No | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories` (default: false) |
258
265
 
259
266
  **Returns:** `{ sessions, message?, isError? }`
260
267
 
268
+ `sessions[]` now includes lightweight diagnostics fields: `pendingPermissionCount`, `eventCount`, `currentCursor`, `lastEventId`, `ttlMs`, `lastError?`, `lastErrorAt?`, and `redactions[]`.
269
+
261
270
  ### `claude_code_check` — Poll events and respond to permission requests
262
271
 
263
272
  Poll session events/results and approve/deny pending permission requests.
264
273
 
265
- | Parameter | Type | Required | Description |
266
- | ------------------- | ------- | ---------------------- | -------------------------------------------------------------------------------------------------------------- |
267
- | `action` | string | Yes | `"poll"` or `"respond_permission"` |
268
- | `sessionId` | string | Yes | Target session ID |
269
- | `cursor` | number | No | Event cursor for incremental polling (`poll` only). Default: omitted (starts from the beginning of the buffer) |
270
- | `responseMode` | string | No | `"minimal"` (default) or `"full"` — controls payload size and redaction behavior |
271
- | `maxEvents` | number | No | Max events per poll (pagination via `nextCursor`). Default: `200` in `"minimal"`; unlimited in `"full"` |
272
- | `requestId` | string | For respond_permission | Permission request ID |
273
- | `decision` | string | For respond_permission | `"allow"` or `"deny"` |
274
- | `denyMessage` | string | No | Deny reason shown to Claude (`deny` only). Default: `"Permission denied by caller"` |
275
- | `interrupt` | boolean | No | When true, denying also interrupts the whole agent (`deny` only). Default: `false` |
276
- | `pollOptions` | object | No | Fine-grained poll control options (see below) |
277
- | `permissionOptions` | object | No | Advanced permission response options (see below) |
274
+ | Parameter | Type | Required | Description |
275
+ | ------------------- | ------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------- |
276
+ | `action` | string | Yes | `"poll"` or `"respond_permission"` |
277
+ | `sessionId` | string | Yes | Target session ID |
278
+ | `cursor` | number | No | Event cursor for incremental polling (`poll` only). Default: omitted (starts from the beginning of the buffer) |
279
+ | `responseMode` | string | No | `"minimal"` (default), `"delta_compact"` (lightweight polling), or `"full"` (verbose diagnostics) |
280
+ | `maxEvents` | number | No | Max events per poll (pagination via `nextCursor`). Default: `200` in `"minimal"`; unlimited in `"full"`/`"delta_compact"` |
281
+ | `requestId` | string | For respond_permission | Permission request ID |
282
+ | `decision` | string | For respond_permission | `"allow"`, `"deny"`, or `"allow_for_session"` |
283
+ | `denyMessage` | string | No | Deny reason shown to Claude (`deny` only). Default: `"Permission denied by caller"` |
284
+ | `interrupt` | boolean | No | When true, denying also interrupts the whole agent (`deny` only). Default: `false` |
285
+ | `pollOptions` | object | No | Fine-grained poll control options (see below) |
286
+ | `permissionOptions` | object | No | Advanced permission response options (see below) |
278
287
 
279
288
  <details>
280
289
  <summary><code>pollOptions</code> object parameters (10 fine-grained poll controls)</summary>
@@ -285,22 +294,22 @@ Poll session events/results and approve/deny pending permission requests.
285
294
  | `pollOptions.includeEvents` | boolean | When false, omits `events` (but `nextCursor` still advances). Default: `true` |
286
295
  | `pollOptions.includeActions` | boolean | When false, omits `actions[]` even if `waiting_permission`. Default: `true` |
287
296
  | `pollOptions.includeResult` | boolean | When false, omits top-level `result` even when `idle`/`error`. Default: `true` |
288
- | `pollOptions.includeUsage` | boolean | Include `result.usage` (default: true in full mode, false in minimal mode) |
289
- | `pollOptions.includeModelUsage` | boolean | Include `result.modelUsage` (default: true in full mode, false in minimal mode) |
290
- | `pollOptions.includeStructuredOutput` | boolean | Include `result.structuredOutput` (default: true in full mode, false in minimal mode) |
291
- | `pollOptions.includeTerminalEvents` | boolean | When true, keeps terminal `result`/`error` events in `events` even if top-level `result` is included. Default: `false` in `"minimal"`, `true` in `"full"` |
292
- | `pollOptions.includeProgressEvents` | boolean | When true, includes progress events (`tool_progress`, `auth_status`) in the events stream. Default: `false` in `"minimal"`, `true` in `"full"` |
293
- | `pollOptions.maxBytes` | number | Approximate max JSON bytes for `events` in this response. When exceeded, events are truncated and `truncatedFields` includes `"events_bytes"`. Default: unlimited |
297
+ | `pollOptions.includeUsage` | boolean | Include `result.usage` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
298
+ | `pollOptions.includeModelUsage` | boolean | Include `result.modelUsage` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
299
+ | `pollOptions.includeStructuredOutput` | boolean | Include `result.structuredOutput` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`) |
300
+ | `pollOptions.includeTerminalEvents` | boolean | When true, keeps terminal `result`/`error` events in `events` even if top-level `result` is included. Default: `false` in `"minimal"`/`"delta_compact"`, `true` in `"full"` |
301
+ | `pollOptions.includeProgressEvents` | boolean | When true, includes progress events (`tool_progress`, `auth_status`) in the events stream. Default: `false` in `"minimal"`/`"delta_compact"`, `true` in `"full"` |
302
+ | `pollOptions.maxBytes` | number | Approximate max JSON bytes for `events` in this response. When exceeded, events are truncated and `truncatedFields` includes `"events_bytes"`. Default: unlimited |
294
303
 
295
304
  </details>
296
305
 
297
306
  <details>
298
307
  <summary><code>permissionOptions</code> object parameters (2 advanced permission response options)</summary>
299
308
 
300
- | Parameter | Type | Description |
301
- | -------------------------------------- | ------ | ----------------------------------------------------------------------- |
302
- | `permissionOptions.updatedInput` | object | Modified tool input to run (`allow` only). Default: none |
303
- | `permissionOptions.updatedPermissions` | array | Permission rule updates suggested/applied (`allow` only). Default: none |
309
+ | Parameter | Type | Description |
310
+ | -------------------------------------- | ------ | ------------------------------------------------------------------------------------------- |
311
+ | `permissionOptions.updatedInput` | object | Modified tool input to run (`allow`/`allow_for_session` only). Default: none |
312
+ | `permissionOptions.updatedPermissions` | array | Permission rule updates suggested/applied (`allow`/`allow_for_session` only). Default: none |
304
313
 
305
314
  </details>
306
315
 
@@ -309,6 +318,7 @@ Poll session events/results and approve/deny pending permission requests.
309
318
  Notes:
310
319
 
311
320
  - On error (e.g. invalid arguments, missing/expired session): `{ sessionId, isError: true, error }`
321
+ - `respond_user_input` is not supported on this backend. Use `respond_permission` for interactive approvals.
312
322
  - Always treat `cursor` as an incremental position: store `nextCursor` and pass it back on the next poll to avoid replaying old events.
313
323
  - If `cursorResetTo` is present, your `cursor` was too old (events were evicted); reset your cursor to `cursorResetTo`.
314
324
  - For safety, de-duplicate events by `event.id` on the client side.
@@ -319,6 +329,7 @@ Notes:
319
329
  - Permission `actions[]` include `timeoutMs`, `expiresAt`, and best-effort `remainingMs` to help callers avoid auto-deny timeouts.
320
330
  - `permission_result` event data is `{ requestId, toolName, behavior, source, message?, interrupt? }` (denial details only present for `deny`).
321
331
  - In `"minimal"` mode (default): assistant message events are slimmed (strips `usage`, `model`, `id`, `cache_control` from content blocks); noisy progress events (`tool_progress`, `auth_status`) are filtered out; `lastEventId`/`lastToolUseId` are omitted; `AgentResult` omits `durationApiMs`/`sessionTotalTurns`/`sessionTotalCostUsd`. Use `responseMode: "full"` or individual `include*` flags to restore any of these.
332
+ - In `"delta_compact"` mode: defaults are optimized for high-frequency polling (`events` and top-level `result` omitted unless explicitly enabled via `pollOptions`), while still returning session status/actions/cursors.
322
333
 
323
334
  ## Usage Example
324
335
 
@@ -364,7 +375,7 @@ while True:
364
375
  final_result = data.get("result")
365
376
  break
366
377
 
367
- # 3) Manage sessions (list/get/cancel)
378
+ # 3) Manage sessions (list/get/cancel/interrupt)
368
379
  result = await mcp.call_tool("claude_code_session", {"action": "list"})
369
380
  ```
370
381
 
@@ -399,11 +410,11 @@ For JSON-based MCP clients (Claude Desktop, Cursor, etc.):
399
410
  For OpenAI Codex CLI (`~/.codex/config.toml`):
400
411
 
401
412
  ```toml
402
- [mcp_servers.claude-code]
413
+ [mcp_servers.claude-code-mcp]
403
414
  command = "npx"
404
415
  args = ["-y", "@leo000001/claude-code-mcp"]
405
416
 
406
- [mcp_servers.claude-code.env]
417
+ [mcp_servers.claude-code-mcp.env]
407
418
  CLAUDE_CODE_GIT_BASH_PATH = "C:\\Program Files\\Git\\bin\\bash.exe"
408
419
  ```
409
420
 
@@ -425,6 +436,7 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
425
436
  - **Async permission approvals** — when a tool call needs approval, the session transitions to `waiting_permission` and surfaces requests via `claude_code_check` (`actions[]`).
426
437
  - **No runtime privilege escalation tool** — permission decisions are per-session (allow/deny lists + explicit approvals), and the server does not expose a `claude_code_configure` bypass switch.
427
438
  - **Environment variables are inherited** — the spawned Claude Code process inherits all environment variables (including `ANTHROPIC_API_KEY`) from the parent process by default. The `advanced.env` parameter **merges** with `process.env` (user-provided values take precedence), so you can safely add or override individual variables without losing existing ones.
439
+ - **Permission policy is enforced in two places** — `allowedTools`/`disallowedTools` are passed to the SDK and also guarded in `canUseTool` as a defensive consistency check (for example, `blockedPath` can still trigger an approval flow).
428
440
  - Tool visibility vs approvals:
429
441
  - Use `advanced.tools` to restrict which tools the agent can _see_ (hidden tools cannot be called).
430
442
  - Use `allowedTools` to auto-approve specific tools without prompting (the SDK may still prompt for path-based restrictions like `blockedPath`).
@@ -437,13 +449,15 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
437
449
 
438
450
  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).
439
451
 
440
- | Variable | Description | Default |
441
- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------- |
442
- | `CLAUDE_CODE_GIT_BASH_PATH` | Path to `bash.exe` on Windows (see [Windows Support](#windows-support)) | Auto-detected |
443
- | `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) |
444
- | `CLAUDE_CODE_MCP_RESUME_SECRET` | HMAC secret used to validate `resumeToken` for disk resume fallback (recommended if disk resume is enabled) | _(unset)_ |
445
- | `CLAUDE_CODE_MCP_MAX_SESSIONS` | Maximum number of in-memory sessions (set `0` to disable the limit) | `128` |
446
- | `CLAUDE_CODE_MCP_MAX_PENDING_PERMISSIONS` | Maximum number of outstanding permission requests per session (set `0` to disable the limit) | `64` |
452
+ | Variable | Description | Default |
453
+ | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------- |
454
+ | `CLAUDE_CODE_GIT_BASH_PATH` | Path to `bash.exe` on Windows (see [Windows Support](#windows-support)) | Auto-detected |
455
+ | `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) |
456
+ | `CLAUDE_CODE_MCP_RESUME_SECRET` | HMAC secret used to validate `resumeToken` for disk resume fallback (recommended if disk resume is enabled) | _(unset)_ |
457
+ | `CLAUDE_CODE_MCP_MAX_SESSIONS` | Maximum number of in-memory sessions (set `0` to disable the limit) | `128` |
458
+ | `CLAUDE_CODE_MCP_MAX_PENDING_PERMISSIONS` | Maximum number of outstanding permission requests per session (set `0` to disable the limit) | `64` |
459
+ | `CLAUDE_CODE_MCP_EVENT_BUFFER_MAX_SIZE` | Soft limit for in-memory event buffer per session (`0` is not supported) | `1000` |
460
+ | `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` |
447
461
 
448
462
  ### How to configure
449
463
 
@@ -464,14 +478,14 @@ All environment variables are optional. They are set on the MCP server process (
464
478
  }
465
479
  ```
466
480
 
467
- **OpenAI Codex CLI** — add an `[mcp_servers.claude-code.env]` section in `~/.codex/config.toml`:
481
+ **OpenAI Codex CLI** — add an `[mcp_servers.claude-code-mcp.env]` section in `~/.codex/config.toml`:
468
482
 
469
483
  ```toml
470
- [mcp_servers.claude-code]
484
+ [mcp_servers.claude-code-mcp]
471
485
  command = "npx"
472
486
  args = ["-y", "@leo000001/claude-code-mcp"]
473
487
 
474
- [mcp_servers.claude-code.env]
488
+ [mcp_servers.claude-code-mcp.env]
475
489
  CLAUDE_CODE_MCP_ALLOW_DISK_RESUME = "1"
476
490
  CLAUDE_CODE_MCP_RESUME_SECRET = "change-me"
477
491
  ```
@@ -530,7 +544,7 @@ MCP Client ←→ (stdio/JSON-RPC) ←→ MCP Server [same machine]
530
544
 
531
545
  **Session persistence:** The MCP server's Session Manager holds **in-memory** session metadata, a snapshot of session options (tool config, limits, `cwd`, allow/deny lists, etc.), and an event buffer used by `claude_code_check`. This metadata is **not** persisted to disk by the MCP server. The actual conversation history is persisted to disk by the Claude Code CLI (under `~/.claude/projects/`) — this is managed by the SDK, not by this MCP server. By default, if the MCP server restarts or the session expires from memory, `claude_code_reply` will return `SESSION_NOT_FOUND` even though the CLI transcript may still exist on disk. You can opt into disk-resume behavior by setting `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1`.
532
546
 
533
- Sessions are automatically cleaned up after 30 minutes of idle time, or after 4 hours of continuous running.
547
+ Sessions are automatically cleaned up after 30 minutes of idle time, or after 4 hours of continuous running (timed-out running sessions transition to `cancelled`).
534
548
 
535
549
  **Turn/Cost semantics:** `numTurns` and `totalCostUsd` are per-call increments. For cumulative per-session totals, use `sessionTotalTurns` and `sessionTotalCostUsd`. When `forkSession=true`, the returned `sessionId` (and `sessionTotal*`) refer to the forked session; the original session totals are preserved.
536
550