@leo000001/claude-code-mcp 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 ## Unreleased
 
+### Security
+
+- Validate `resumeToken` using timing-safe comparison (`timingSafeEqual` for fixed-length HMAC tokens) to reduce timing side-channel risk.
+
+### Improvements
+
+- 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.
+- Add configurable event-buffer limits via `CLAUDE_CODE_MCP_EVENT_BUFFER_MAX_SIZE` and `CLAUDE_CODE_MCP_EVENT_BUFFER_HARD_MAX_SIZE`.
+- 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.
+
+### Documentation
+
+- 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).
+
+### Tests
+
+- Add dedicated tests for `resume-token` and `claude-code-reply`.
+- Extend tests for event-buffer behavior, resource metadata, and runtime resource notifications.
+
+## 2.2.0 (2026-02-17)
+
 ### Improvements
 
 - Add `CLAUDE_CODE_MCP_MAX_SESSIONS` (default: `128`) to cap in-memory session count and reduce risk of memory exhaustion.
@@ -60,8 +86,9 @@
 - `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`.
 - Removed tool: `claude_code_configure`
 - New tool: `claude_code_check` (poll + respond_permission)
+- Legacy `bypassPermissions` mode is no longer exposed in MCP schemas for 2.x.
 - **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:
-  - `claude_code`: 22 low-frequency params moved into `advanced` object (e.g. `effort` → `advanced.effort`, `tools` → `advanced.tools`, `agents` → `advanced.agents`, `env` → `advanced.env`)
+  - `claude_code`: 22 low-frequency params moved into `advanced` object in 2.0.0 (current versions expose 20 low-frequency params + 2 compatibility aliases: `advanced.effort`, `advanced.thinking`)
   - `claude_code_reply`: 28 disk-resume params moved into `diskResumeConfig` object (e.g. `resumeToken` → `diskResumeConfig.resumeToken`, `cwd` → `diskResumeConfig.cwd`)
   - `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`)
 

package/CONTRIBUTING.md

@@ -10,6 +10,13 @@ cd claude-code-mcp
 npm install
 ```
 
+### Local Environment Requirements
+
+- Node.js `>=18` (Node 20/22 recommended for local development)
+- npm (bundled with Node)
+- Windows contributors: install **Git for Windows** (`bash.exe`) for Claude Code CLI compatibility
+- Optional: set `CLAUDE_CODE_GIT_BASH_PATH` explicitly when testing MCP clients launched outside your terminal environment
+
 ## Development Workflow
 
 1. Create a feature branch from the default branch

package/README.md

@@ -8,6 +8,8 @@ MCP server that wraps [Claude Code (Claude Agent SDK)](https://docs.anthropic.co
 
 Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sdk/) design philosophy — minimum tools, maximum capability.
 
+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.
+
 ## Features
 
 - **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.):
 }
 ```
 
-> 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.
+> 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.
 
 ### Anthropic Claude Code CLI (as an MCP client)
 
@@ -174,7 +176,7 @@ Continue an existing session by sending a follow-up message. The agent retains f
 | `forkSession`                | boolean | No       | Create a branched copy of this session. Default: `false`                                                             |
 | `effort`                     | string  | No       | Effort level override for this run (and for future replies when not forking). Default: SDK/Claude Code default      |
 | `thinking`                   | object  | No       | Thinking mode override for this run (and for future replies when not forking). Default: SDK/Claude Code default     |
-| `permissionRequestTimeoutMs` | number  | No       | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000`                      |
+| `permissionRequestTimeoutMs` | number  | No       | Timeout in milliseconds waiting for permission decisions, auto-deny on expiry. Default: `60000` (server-clamped to 5min) |
 | `sessionInitTimeoutMs`       | number  | No       | Fork init timeout in milliseconds (only when `forkSession=true`). Default: `10000`                                   |
 | `diskResumeConfig`           | object  | No       | Disk resume parameters (see below). Used when `CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1` and in-memory session is missing |
 
@@ -233,31 +235,42 @@ Gotchas:
 - 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.
 - `TeamDelete` may require members to reach `shutdown_approved` (otherwise you may see "active member" errors); cleanup can be asynchronous during shutdown.
 - Skills may become available later in the same session (early calls may show "Unknown", later succeed after skills are loaded/registered).
+- `toolCatalogCount` and `availableTools` are different views: catalog is server-known tools, while `availableTools` comes from each session's runtime `system/init.tools`.
 - Some internal features (e.g. ToolSearch) may not appear in `availableTools` (derived from SDK `system/init.tools`).
 
 ### Resources
 
 If your MCP client supports resources, this server exposes a couple of **read-only** MCP resources:
 
-- `claude-code-mcp:///server-info` (JSON): server metadata (version/platform/runtime)
-- `claude-code-mcp:///internal-tools` (JSON): internal tool catalog (runtime-aware)
+- `claude-code-mcp:///server-info` (JSON): server metadata (version/platform/runtime + capabilities/limits)
+- `claude-code-mcp:///internal-tools` (JSON): internal tool catalog (runtime-aware, includes permission/schema metadata)
 - `claude-code-mcp:///gotchas` (Markdown): practical limits/gotchas
-- `claude-code-mcp:///compat-report` (JSON): compatibility report (transport/platform assumptions, runtime warnings, guidance)
+- `claude-code-mcp:///quickstart` (Markdown): minimal async start/poll/respond flow
+- `claude-code-mcp:///errors` (JSON): structured error-code catalog and remediation hints
+- `claude-code-mcp:///compat-report` (JSON): compatibility report (transport/platform assumptions, runtime warnings, guidance, recommended settings, tool count diagnostics)
+
+Resource templates:
+
+- `claude-code-mcp:///session/{sessionId}`: lightweight session snapshot for a specific session
+- `claude-code-mcp:///tools/runtime{?sessionId}`: runtime tool view globally or per session
+- `claude-code-mcp:///compat/diff{?client}`: client-specific compatibility guidance
 
 **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).
 
 ### `claude_code_session` — Manage sessions
 
-List, inspect, or cancel sessions.
+List, inspect, cancel, or interrupt sessions.
 
-| Parameter          | Type    | Required       | Description                                                                    |
-| ------------------ | ------- | -------------- | ------------------------------------------------------------------------------ |
-| `action`           | string  | Yes            | `"list"`, `"get"`, or `"cancel"`                                               |
-| `sessionId`        | string  | For get/cancel | Target session ID                                                              |
+| Parameter          | Type    | Required                  | Description                                                                    |
+| ------------------ | ------- | ------------------------- | ------------------------------------------------------------------------------ |
+| `action`           | string  | Yes                       | `"list"`, `"get"`, `"cancel"`, or `"interrupt"`                               |
+| `sessionId`        | string  | For get/cancel/interrupt  | Target session ID                                                              |
 | `includeSensitive` | boolean | No             | Include `cwd`/`systemPrompt`/`agents`/`additionalDirectories` (default: false) |
 
 **Returns:** `{ sessions, message?, isError? }`
 
+`sessions[]` now includes lightweight diagnostics fields: `pendingPermissionCount`, `eventCount`, `currentCursor`, `lastEventId`, `ttlMs`, `lastError?`, `lastErrorAt?`, and `redactions[]`.
+
 ### `claude_code_check` — Poll events and respond to permission requests
 
 Poll session events/results and approve/deny pending permission requests.
@@ -267,10 +280,10 @@ Poll session events/results and approve/deny pending permission requests.
 | `action`            | string  | Yes                    | `"poll"` or `"respond_permission"`                                                                             |
 | `sessionId`         | string  | Yes                    | Target session ID                                                                                              |
 | `cursor`            | number  | No                     | Event cursor for incremental polling (`poll` only). Default: omitted (starts from the beginning of the buffer) |
-| `responseMode`      | string  | No                     | `"minimal"` (default) or `"full"` — controls payload size and redaction behavior                               |
-| `maxEvents`         | number  | No                     | Max events per poll (pagination via `nextCursor`). Default: `200` in `"minimal"`; unlimited in `"full"`        |
+| `responseMode`      | string  | No                     | `"minimal"` (default), `"delta_compact"` (lightweight polling), or `"full"` (verbose diagnostics)               |
+| `maxEvents`         | number  | No                     | Max events per poll (pagination via `nextCursor`). Default: `200` in `"minimal"`; unlimited in `"full"`/`"delta_compact"` |
 | `requestId`         | string  | For respond_permission | Permission request ID                                                                                          |
-| `decision`          | string  | For respond_permission | `"allow"` or `"deny"`                                                                                          |
+| `decision`          | string  | For respond_permission | `"allow"`, `"deny"`, or `"allow_for_session"`                                                                  |
 | `denyMessage`       | string  | No                     | Deny reason shown to Claude (`deny` only). Default: `"Permission denied by caller"`                            |
 | `interrupt`         | boolean | No                     | When true, denying also interrupts the whole agent (`deny` only). Default: `false`                             |
 | `pollOptions`       | object  | No                     | Fine-grained poll control options (see below)                                                                  |
@@ -285,11 +298,11 @@ Poll session events/results and approve/deny pending permission requests.
 | `pollOptions.includeEvents`           | boolean | When false, omits `events` (but `nextCursor` still advances). Default: `true`                                                                                                           |
 | `pollOptions.includeActions`          | boolean | When false, omits `actions[]` even if `waiting_permission`. Default: `true`                                                                                                             |
 | `pollOptions.includeResult`           | boolean | When false, omits top-level `result` even when `idle`/`error`. Default: `true`                                                                                                          |
-| `pollOptions.includeUsage`            | boolean | Include `result.usage` (default: true in full mode, false in minimal mode)                                                                                                              |
-| `pollOptions.includeModelUsage`       | boolean | Include `result.modelUsage` (default: true in full mode, false in minimal mode)                                                                                                         |
-| `pollOptions.includeStructuredOutput` | boolean | Include `result.structuredOutput` (default: true in full mode, false in minimal mode)                                                                                                   |
-| `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"`                               |
-| `pollOptions.includeProgressEvents`   | boolean | When true, includes progress events (`tool_progress`, `auth_status`) in the events stream. Default: `false` in `"minimal"`, `true` in `"full"`                                          |
+| `pollOptions.includeUsage`            | boolean | Include `result.usage` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`)                                                                                         |
+| `pollOptions.includeModelUsage`       | boolean | Include `result.modelUsage` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`)                                                                                    |
+| `pollOptions.includeStructuredOutput` | boolean | Include `result.structuredOutput` (default: `true` in `"full"`, `false` in `"minimal"`/`"delta_compact"`)                                                                              |
+| `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"`            |
+| `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"`                       |
 | `pollOptions.maxBytes`                | number  | Approximate max JSON bytes for `events` in this response. When exceeded, events are truncated and `truncatedFields` includes `"events_bytes"`. Default: unlimited                         |
 
 </details>
@@ -299,8 +312,8 @@ Poll session events/results and approve/deny pending permission requests.
 
 | Parameter                              | Type   | Description                                                             |
 | -------------------------------------- | ------ | ----------------------------------------------------------------------- |
-| `permissionOptions.updatedInput`       | object | Modified tool input to run (`allow` only). Default: none                |
-| `permissionOptions.updatedPermissions` | array  | Permission rule updates suggested/applied (`allow` only). Default: none |
+| `permissionOptions.updatedInput`       | object | Modified tool input to run (`allow`/`allow_for_session` only). Default: none                |
+| `permissionOptions.updatedPermissions` | array  | Permission rule updates suggested/applied (`allow`/`allow_for_session` only). Default: none |
 
 </details>
 
@@ -309,6 +322,7 @@ Poll session events/results and approve/deny pending permission requests.
 Notes:
 
 - On error (e.g. invalid arguments, missing/expired session): `{ sessionId, isError: true, error }`
+- `respond_user_input` is not supported on this backend. Use `respond_permission` for interactive approvals.
 - Always treat `cursor` as an incremental position: store `nextCursor` and pass it back on the next poll to avoid replaying old events.
 - If `cursorResetTo` is present, your `cursor` was too old (events were evicted); reset your cursor to `cursorResetTo`.
 - For safety, de-duplicate events by `event.id` on the client side.
@@ -319,6 +333,7 @@ Notes:
 - Permission `actions[]` include `timeoutMs`, `expiresAt`, and best-effort `remainingMs` to help callers avoid auto-deny timeouts.
 - `permission_result` event data is `{ requestId, toolName, behavior, source, message?, interrupt? }` (denial details only present for `deny`).
 - 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.
+- 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.
 
 ## Usage Example
 
@@ -364,7 +379,7 @@ while True:
         final_result = data.get("result")
         break
 
-# 3) Manage sessions (list/get/cancel)
+# 3) Manage sessions (list/get/cancel/interrupt)
 result = await mcp.call_tool("claude_code_session", {"action": "list"})
 ```
 
@@ -425,6 +440,7 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
 - **Async permission approvals** — when a tool call needs approval, the session transitions to `waiting_permission` and surfaces requests via `claude_code_check` (`actions[]`).
 - **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.
 - **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.
+- **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).
 - Tool visibility vs approvals:
   - Use `advanced.tools` to restrict which tools the agent can _see_ (hidden tools cannot be called).
   - Use `allowedTools` to auto-approve specific tools without prompting (the SDK may still prompt for path-based restrictions like `blockedPath`).
@@ -444,6 +460,8 @@ All environment variables are optional. They are set on the MCP server process (
 | `CLAUDE_CODE_MCP_RESUME_SECRET`     | HMAC secret used to validate `resumeToken` for disk resume fallback (recommended if disk resume is enabled)      | _(unset)_      |
 | `CLAUDE_CODE_MCP_MAX_SESSIONS`      | Maximum number of in-memory sessions (set `0` to disable the limit)                                              | `128`          |
 | `CLAUDE_CODE_MCP_MAX_PENDING_PERMISSIONS` | Maximum number of outstanding permission requests per session (set `0` to disable the limit)                | `64`           |
+| `CLAUDE_CODE_MCP_EVENT_BUFFER_MAX_SIZE` | Soft limit for in-memory event buffer per session (`0` is not supported)                                      | `1000`         |
+| `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`         |
 
 ### How to configure
 
@@ -530,7 +548,7 @@ MCP Client ←→ (stdio/JSON-RPC) ←→ MCP Server     [same machine]
 
 **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`.
 
-Sessions are automatically cleaned up after 30 minutes of idle time, or after 4 hours of continuous running.
+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`).
 
 **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.