@leo000001/claude-code-mcp 1.4.0 → 1.6.0

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 (8) hide show
  1. package/CHANGELOG.md +15 -1
  2. package/CODE_OF_CONDUCT.md +4 -4
  3. package/CONTRIBUTING.md +2 -2
  4. package/README.md +97 -28
  5. package/dist/index.js +112 -50
  6. package/dist/index.js.map +1 -1
  7. package/package.json +4 -2
  8. package/DESIGN.md +0 -238
package/CHANGELOG.md CHANGED
@@ -1,6 +1,20 @@
1
1
  # Changelog
2
2
 
3
- ## 1.1.0 (2026-02-11)
3
+ ## 1.5.0 (2026-02-12)
4
+
5
+ ### Bug Fixes
6
+ - Windows: fixed Git Bash auto-detection path derivation and improved candidate search
7
+ - Server: internal exceptions in `claude_code`/`claude_code_reply` now return JSON-shaped error results (consistent parsing)
8
+ - Server: tightened input validation for `prompt`, `sessionId`, and `cwd` (trim + non-empty)
9
+
10
+ ### Security
11
+ - `claude_code_session includeSensitive=true` no longer leaks extra fields (e.g. `env`, `debugFile`, `mcpServers`, `sandbox`) beyond the documented sensitive set
12
+
13
+ ### Documentation
14
+ - README: clarify `Task` is required for subagent invocation and how `allowedTools` interacts with `mcpServers`
15
+ - README: clarify `includePartialMessages` is not streamed over MCP responses
16
+
17
+ ## 1.4.0 (2026-02-11)
4
18
 
5
19
  ### Features
6
20
  - New tool: `claude_code_configure` for runtime bypass mode management (enable/disable without restart)
package/CODE_OF_CONDUCT.md CHANGED
@@ -28,10 +28,10 @@ Examples of unacceptable behavior:
28
28
 
29
29
  ## Enforcement
30
30
 
31
- Instances of abusive, harassing, or otherwise unacceptable behavior may be
32
- reported privately via [GitHub Security Advisories](https://github.com/xihuai18/claude-code-mcp/security/advisories/new)
33
- (preferred for sensitive reports), or publicly via
34
- [GitHub Issues](https://github.com/xihuai18/claude-code-mcp/issues) for non-sensitive matters.
31
+ Instances of abusive, harassing, or otherwise unacceptable behavior may be reported:
32
+
33
+ - Privately via [GitHub Security Advisories](https://github.com/xihuai18/claude-code-mcp/security/advisories/new) (preferred for sensitive reports)
34
+ - Publicly via [GitHub Issues](https://github.com/xihuai18/claude-code-mcp/issues) for non-sensitive matters
35
35
 
36
36
  For security vulnerabilities, please follow [SECURITY.md](SECURITY.md).
37
37
 
package/CONTRIBUTING.md CHANGED
@@ -12,7 +12,7 @@ npm install
12
12
 
13
13
  ## Development Workflow
14
14
 
15
- 1. Create a feature branch from `main`
15
+ 1. Create a feature branch from the default branch
16
16
  2. Make your changes
17
17
  3. Ensure all checks pass:
18
18
  ```bash
@@ -22,7 +22,7 @@ npm install
22
22
  npm run format:check # Prettier
23
23
  ```
24
24
  4. Commit your changes (pre-commit hooks will run lint-staged + typecheck + test)
25
- 5. Open a Pull Request against `main`
25
+ 5. Open a Pull Request against the default branch
26
26
 
27
27
  ## Code Style
28
28
 
package/README.md CHANGED
@@ -1,17 +1,19 @@
1
1
  # claude-code-mcp
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/@leo000001/claude-code-mcp.svg)](https://www.npmjs.com/package/@leo000001/claude-code-mcp)
4
+ [![license](https://img.shields.io/npm/l/@leo000001/claude-code-mcp.svg)](https://github.com/xihuai18/claude-code-mcp/blob/HEAD/LICENSE)
5
+ [![node](https://img.shields.io/node/v/@leo000001/claude-code-mcp.svg)](https://nodejs.org)
6
+
3
7
  MCP server that wraps [Claude Code (Claude Agent SDK)](https://docs.anthropic.com/en/docs/claude-code/overview) as tools, enabling any MCP client to invoke Claude Code for autonomous coding tasks.
4
8
 
5
9
  Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sdk/) design philosophy — minimum tools, maximum capability.
6
10
 
7
- **npm package:** [@leo000001/claude-code-mcp](https://www.npmjs.com/package/@leo000001/claude-code-mcp)
8
-
9
11
  ## Features
10
12
 
11
13
  - **4 tools** covering the full agent lifecycle: start, continue, manage, configure
12
14
  - **Session management** with resume and fork support
13
15
  - **Local settings loaded by default** — automatically reads `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, and `CLAUDE.md` so the agent behaves like your local Claude Code CLI
14
- - **Fine-grained permissions** — tool whitelist/blacklist, permission modes
16
+ - **Fine-grained permissions** — tool allow/deny lists, permission modes
15
17
  - **Custom subagents** — define specialized agents per session
16
18
  - **Cost tracking** — per-session turn and cost accounting
17
19
  - **Session cancellation** via AbortController
@@ -20,6 +22,8 @@ Inspired by the [Codex MCP](https://developers.openai.com/codex/guides/agents-sd
20
22
 
21
23
  ## Prerequisites
22
24
 
25
+ - **Node.js >= 18** is required.
26
+
23
27
  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.
24
28
 
25
29
  - The SDK's bundled CLI version is determined by the SDK package version (e.g. SDK 0.2.38 = Claude Code 2.1.38)
@@ -33,6 +37,12 @@ This MCP server uses the [`@anthropic-ai/claude-agent-sdk`](https://www.npmjs.co
33
37
 
34
38
  ### As an MCP server (recommended)
35
39
 
40
+ Install globally or use `npx` (no install needed):
41
+
42
+ ```bash
43
+ npm install -g @leo000001/claude-code-mcp
44
+ ```
45
+
36
46
  Add to your MCP client configuration (Claude Desktop, Cursor, etc.):
37
47
 
38
48
  ```json
@@ -40,7 +50,7 @@ Add to your MCP client configuration (Claude Desktop, Cursor, etc.):
40
50
  "mcpServers": {
41
51
  "claude-code": {
42
52
  "command": "npx",
43
- "args": ["@leo000001/claude-code-mcp"]
53
+ "args": ["-y", "@leo000001/claude-code-mcp"]
44
54
  }
45
55
  }
46
56
  }
@@ -76,21 +86,21 @@ npm start
76
86
 
77
87
  ### `claude_code` — Start a new session
78
88
 
79
- Start a Claude Code agent that can read/write files, run commands, and more.
89
+ 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.
80
90
 
81
91
  | Parameter | Type | Required | Description |
82
92
  | ---------------------------- | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
83
93
  | `prompt` | string | Yes | Task or question for Claude Code |
84
94
  | `cwd` | string | No | Working directory (defaults to server cwd) |
85
- | `allowedTools` | string[] | No | Auto-approved tools (skips permission prompts). In `"dontAsk"` mode this effectively acts as a whitelist |
86
- | `disallowedTools` | string[] | No | Tool blacklist |
87
- | `tools` | string[] \| object | No | Base set of available tools (array of names, or `{ type: "preset", preset: "claude_code" }`) |
95
+ | `allowedTools` | string[] | No | List of tool names the agent can use without permission prompts. In `"dontAsk"` mode, only tools in this list are available. Example: `["Bash", "Read", "Write", "Edit"]` |
96
+ | `disallowedTools` | string[] | No | List of tool names the agent is forbidden from using. Takes precedence over `allowedTools` |
97
+ | `tools` | string[] \| object | No | Define the base tool set. Array of tool name strings, or `{ type: "preset", preset: "claude_code" }` for the default toolset. `allowedTools`/`disallowedTools` further filter on top of this |
88
98
  | `persistSession` | boolean | No | Persist session history to disk (`~/.claude/projects/`). Default: `true`. Set `false` to disable. |
89
- | `permissionMode` | string | No | Defaults to `"dontAsk"`. Options: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`, `"delegate"`, `"dontAsk"` |
90
- | `maxTurns` | number | No | Maximum agentic turns |
99
+ | `permissionMode` | string | No | Controls how the agent handles tool permissions. Defaults to `"dontAsk"`. Options: `"default"`, `"acceptEdits"`, `"bypassPermissions"`, `"plan"`, `"delegate"`, `"dontAsk"` |
100
+ | `maxTurns` | number | No | Maximum number of agent reasoning steps. Each step may involve one or more tool calls |
91
101
  | `model` | string | No | Model to use (e.g. `"claude-sonnet-4-5-20250929"`) |
92
- | `systemPrompt` | string \| object | No | Custom system prompt (string or `{ type: "preset", preset: "claude_code", append?: "..." }`) |
93
- | `agents` | object | No | Custom subagent definitions |
102
+ | `systemPrompt` | string \| object | No | Override the agent's system prompt. Pass a string for full replacement, or `{ type: "preset", preset: "claude_code", append?: "..." }` to extend the default prompt |
103
+ | `agents` | object | No | Define custom sub-agents the main agent can delegate tasks to. Each key is the agent name; value specifies prompt, tools, model, etc. |
94
104
  | `maxBudgetUsd` | number | No | Maximum budget in USD |
95
105
  | `timeout` | number | No | Timeout in milliseconds for this session |
96
106
  | `effort` | string | No | Effort level: `"low"`, `"medium"`, `"high"`, `"max"` |
@@ -99,12 +109,12 @@ Start a Claude Code agent that can read/write files, run commands, and more.
99
109
  | `outputFormat` | object | No | Structured output: `{ type: "json_schema", schema: {...} }`. Omit for plain text |
100
110
  | `thinking` | object | No | Thinking mode: `{ type: "adaptive" }`, `{ type: "enabled", budgetTokens: N }`, or `{ type: "disabled" }` |
101
111
  | `pathToClaudeCodeExecutable` | string | No | Path to a custom Claude Code executable |
102
- | `agent` | string | No | Main-thread agent name to apply custom agent system prompt, tool restrictions, and model |
112
+ | `agent` | string | No | Name of a custom agent (defined in `agents`) to use as the primary agent, applying its system prompt, tool restrictions, and model |
103
113
  | `mcpServers` | object | No | MCP server configurations (key: server name, value: server config) |
104
- | `sandbox` | object | No | Sandbox settings for command execution isolation |
114
+ | `sandbox` | object | No | Sandbox configuration for isolating shell command execution (e.g., Docker container settings) |
105
115
  | `fallbackModel` | string | No | Fallback model if the primary model fails or is unavailable |
106
116
  | `enableFileCheckpointing` | boolean | No | Enable file checkpointing to track file changes during the session |
107
- | `includePartialMessages` | boolean | No | Include partial/streaming message events in output |
117
+ | `includePartialMessages` | boolean | No | When true, includes intermediate streaming messages in the response. Useful for real-time progress monitoring. Default: false |
108
118
  | `strictMcpConfig` | boolean | No | Enforce strict validation of MCP server configurations |
109
119
  | `settingSources` | string[] | No | Which filesystem settings to load. Defaults to `["user", "project", "local"]` (loads all settings and CLAUDE.md). Pass `[]` for SDK isolation mode |
110
120
  | `debug` | boolean | No | Enable debug mode for verbose logging |
@@ -113,15 +123,20 @@ Start a Claude Code agent that can read/write files, run commands, and more.
113
123
 
114
124
  **Returns:** `{ sessionId, result, isError, durationMs, durationApiMs?, numTurns, totalCostUsd, sessionTotalTurns?, sessionTotalCostUsd?, structuredOutput?, stopReason?, errorSubtype?, usage?, modelUsage?, permissionDenials? }`
115
125
 
126
+ > Notes:
127
+ > - **Subagents require the `Task` tool** to be available to the primary agent. If you use `allowedTools`, include `"Task"` or the agent will be unable to invoke subagents.
128
+ > - If you configure `mcpServers` and want the agent to call tools from those servers, you must also allow them via `allowedTools` (e.g. `"mcp__my_server__*"` or specific tool names), especially in `permissionMode="dontAsk"`.
129
+ > - `includePartialMessages` affects the underlying SDK event stream, but **this MCP server returns a single final JSON result** (it does not stream intermediate events over MCP responses).
130
+
116
131
  ### `claude_code_reply` — Continue a session
117
132
 
118
- Continue an existing session with full context preserved.
133
+ 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.
119
134
 
120
135
  | Parameter | Type | Required | Description |
121
136
  | ------------- | ------- | -------- | --------------------------------------------- |
122
137
  | `sessionId` | string | Yes | Session ID from a previous `claude_code` call |
123
138
  | `prompt` | string | Yes | Follow-up prompt |
124
- | `forkSession` | boolean | No | Fork to a new session (preserves original) |
139
+ | `forkSession` | boolean | No | Create a branched copy of this session. The original remains unchanged; the new session diverges from this point |
125
140
  | `timeout` | number | No | Timeout in milliseconds for this reply |
126
141
 
127
142
  <details>
@@ -130,15 +145,15 @@ Continue an existing session with full context preserved.
130
145
  | Parameter | Type | Description |
131
146
  | ---------------------------- | ------------------ | --------------------------------------------------- |
132
147
  | `cwd` | string | Working directory |
133
- | `allowedTools` | string[] | Auto-approved tools |
134
- | `disallowedTools` | string[] | Tool blacklist |
135
- | `tools` | string[] \| object | Base set of available tools |
148
+ | `allowedTools` | string[] | Auto-approved tool names (see `claude_code` tool) |
149
+ | `disallowedTools` | string[] | Forbidden tool names (see `claude_code` tool) |
150
+ | `tools` | string[] \| object | Base tool set (see `claude_code` tool) |
136
151
  | `persistSession` | boolean | Persist session history to disk |
137
152
  | `permissionMode` | string | Permission mode |
138
- | `maxTurns` | number | Maximum agentic turns |
153
+ | `maxTurns` | number | Maximum number of agent reasoning steps |
139
154
  | `model` | string | Model to use |
140
- | `systemPrompt` | string \| object | Custom system prompt |
141
- | `agents` | object | Custom subagent definitions |
155
+ | `systemPrompt` | string \| object | Override the agent's system prompt |
156
+ | `agents` | object | Custom sub-agent definitions (see `claude_code`) |
142
157
  | `maxBudgetUsd` | number | Maximum budget in USD |
143
158
  | `effort` | string | Effort level |
144
159
  | `betas` | string[] | Beta features |
@@ -147,12 +162,12 @@ Continue an existing session with full context preserved.
147
162
  | `thinking` | object | Thinking mode |
148
163
  | `resumeSessionAt` | string | Resume up to a specific message UUID |
149
164
  | `pathToClaudeCodeExecutable` | string | Path to Claude Code executable |
150
- | `agent` | string | Main-thread agent name |
165
+ | `agent` | string | Primary agent name (see `claude_code` tool) |
151
166
  | `mcpServers` | object | MCP server configurations |
152
- | `sandbox` | object | Sandbox settings |
167
+ | `sandbox` | object | Sandbox config for command isolation |
153
168
  | `fallbackModel` | string | Fallback model |
154
169
  | `enableFileCheckpointing` | boolean | Enable file checkpointing |
155
- | `includePartialMessages` | boolean | Include partial message events |
170
+ | `includePartialMessages` | boolean | Include intermediate streaming messages |
156
171
  | `strictMcpConfig` | boolean | Strict MCP config validation |
157
172
  | `settingSources` | string[] | Which filesystem settings to load (defaults to all) |
158
173
  | `debug` | boolean | Debug mode |
@@ -236,7 +251,7 @@ For JSON-based MCP clients (Claude Desktop, Cursor, etc.):
236
251
  "mcpServers": {
237
252
  "claude-code": {
238
253
  "command": "npx",
239
- "args": ["@leo000001/claude-code-mcp"],
254
+ "args": ["-y", "@leo000001/claude-code-mcp"],
240
255
  "env": {
241
256
  "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
242
257
  }
@@ -273,10 +288,64 @@ setx CLAUDE_CODE_GIT_BASH_PATH "C:\Program Files\Git\bin\bash.exe"
273
288
  - **`permissionMode` defaults to `"dontAsk"`** — the agent will deny any operation not pre-approved, avoiding interactive prompts that would hang in MCP context.
274
289
  - **`bypassPermissions` is disabled by default.** Use the `claude_code_configure` tool with action `enable_bypass` to enable it at runtime.
275
290
  - **Environment variables are inherited** — the spawned Claude Code process inherits all environment variables (including `ANTHROPIC_API_KEY`) from the parent process by default. The `env` parameter **merges** with `process.env` (user-provided values take precedence), so you can safely add or override individual variables without losing existing ones.
276
- - Use `tools` / `disallowedTools` to restrict the base set of tools the agent can use. Use `allowedTools` to auto-approve tools without prompting.
291
+ - Use `tools` / `disallowedTools` to restrict the base set of tools the agent can use. Use `allowedTools` to specify which tools are auto-approved without prompting.
277
292
  - `maxTurns` and `maxBudgetUsd` prevent runaway execution.
278
293
  - Sessions auto-expire after 30 minutes of inactivity.
279
294
 
295
+ ## Environment Variables
296
+
297
+ 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).
298
+
299
+ | Variable | Description | Default |
300
+ | --- | --- | --- |
301
+ | `CLAUDE_CODE_GIT_BASH_PATH` | Path to `bash.exe` on Windows (see [Windows Support](#windows-support)) | Auto-detected |
302
+ | `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) |
303
+ | `CLAUDE_CODE_MCP_ALLOW_SENSITIVE_SESSION_DETAILS` | Set to `1` to allow `claude_code_session` to return `cwd`, `systemPrompt`, `agents`, `additionalDirectories` | `0` (disabled) |
304
+ | `CLAUDE_CODE_MCP_SESSION_TTL_MS` | Idle session time-to-live in milliseconds | `1800000` (30 min) |
305
+ | `CLAUDE_CODE_MCP_RUNNING_SESSION_MAX_MS` | Maximum wall-clock time for a running session before forced cleanup | `14400000` (4 hr) |
306
+ | `CLAUDE_CODE_MCP_CLEANUP_INTERVAL_MS` | How often the cleanup timer runs | `60000` (1 min) |
307
+
308
+ ### How to configure
309
+
310
+ **JSON-based MCP clients** (Claude Desktop, Cursor, etc.) — add an `"env"` block:
311
+
312
+ ```json
313
+ {
314
+ "mcpServers": {
315
+ "claude-code": {
316
+ "command": "npx",
317
+ "args": ["-y", "@leo000001/claude-code-mcp"],
318
+ "env": {
319
+ "CLAUDE_CODE_MCP_ALLOW_DISK_RESUME": "1",
320
+ "CLAUDE_CODE_MCP_SESSION_TTL_MS": "3600000"
321
+ }
322
+ }
323
+ }
324
+ }
325
+ ```
326
+
327
+ **OpenAI Codex CLI** — add an `[mcp_servers.claude-code.env]` section in `~/.codex/config.toml`:
328
+
329
+ ```toml
330
+ [mcp_servers.claude-code]
331
+ command = "npx"
332
+ args = ["-y", "@leo000001/claude-code-mcp"]
333
+
334
+ [mcp_servers.claude-code.env]
335
+ CLAUDE_CODE_MCP_ALLOW_DISK_RESUME = "1"
336
+ CLAUDE_CODE_MCP_SESSION_TTL_MS = "3600000"
337
+ ```
338
+
339
+ **System-wide** — set via your shell profile or OS settings so all processes inherit them:
340
+
341
+ ```bash
342
+ # bash / zsh
343
+ export CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1
344
+
345
+ # PowerShell (permanent, requires new terminal)
346
+ setx CLAUDE_CODE_MCP_ALLOW_DISK_RESUME 1
347
+ ```
348
+
280
349
  ## Development
281
350
 
282
351
  ```bash
package/dist/index.js CHANGED
@@ -127,10 +127,24 @@ var SessionManager = class {
127
127
  }
128
128
  }
129
129
  }
130
- /** Serialize session info for external consumption (strip internal fields) */
130
+ /**
131
+ * Serialize session info for external consumption.
132
+ * Prefer explicit serializers below. This method is kept for backward compatibility
133
+ * but returns the redacted public shape.
134
+ */
131
135
  toJSON(info) {
132
- const { abortController: _, ...rest } = info;
133
- return rest;
136
+ return this.toPublicJSON(info);
137
+ }
138
+ /** Serialize session info when includeSensitive=true (still excludes secrets like env) */
139
+ toSensitiveJSON(info) {
140
+ const base = this.toPublicJSON(info);
141
+ return {
142
+ ...base,
143
+ cwd: info.cwd,
144
+ systemPrompt: info.systemPrompt,
145
+ agents: info.agents,
146
+ additionalDirectories: info.additionalDirectories
147
+ };
134
148
  }
135
149
  /** Serialize session info for listing/inspection (redacts sensitive fields) */
136
150
  toPublicJSON(info) {
@@ -182,24 +196,46 @@ var DEFAULT_SETTING_SOURCES = ["user", "project", "local"];
182
196
  // src/utils/windows.ts
183
197
  import { existsSync } from "fs";
184
198
  import { execSync } from "child_process";
185
- import { join, dirname } from "path";
199
+ import { join, dirname, normalize } from "path";
186
200
  function isWindows() {
187
201
  return process.platform === "win32";
188
202
  }
189
203
  function findGitBash() {
190
- if (process.env.CLAUDE_CODE_GIT_BASH_PATH) {
191
- if (existsSync(process.env.CLAUDE_CODE_GIT_BASH_PATH)) {
192
- return process.env.CLAUDE_CODE_GIT_BASH_PATH;
193
- }
204
+ const envPathRaw = process.env.CLAUDE_CODE_GIT_BASH_PATH;
205
+ if (envPathRaw && envPathRaw.trim() !== "") {
206
+ const envPath = normalize(envPathRaw.trim().replace(/^"|"$/g, ""));
207
+ if (existsSync(envPath)) return envPath;
194
208
  return null;
195
209
  }
196
210
  try {
197
- const gitPath = execSync("where git", { encoding: "utf8" }).trim().split(/\r?\n/)[0];
198
- if (gitPath) {
199
- const bashPath = join(dirname(gitPath), "..", "..", "bin", "bash.exe");
200
- if (existsSync(bashPath)) return bashPath;
201
- const bashPath2 = join(dirname(gitPath), "bash.exe");
202
- if (existsSync(bashPath2)) return bashPath2;
211
+ const output = execSync("where git", { encoding: "utf8" });
212
+ const gitCandidates = output.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
213
+ for (const gitPathRaw of gitCandidates) {
214
+ const gitPath = normalize(gitPathRaw.replace(/^"|"$/g, ""));
215
+ if (!gitPath) continue;
216
+ const gitDir = dirname(gitPath);
217
+ const gitDirLower = gitDir.toLowerCase();
218
+ const roots = /* @__PURE__ */ new Set();
219
+ roots.add(gitDir);
220
+ roots.add(join(gitDir, ".."));
221
+ roots.add(join(gitDir, "..", ".."));
222
+ if (gitDirLower.endsWith("\\cmd") || gitDirLower.endsWith("\\bin")) {
223
+ roots.add(join(gitDir, ".."));
224
+ }
225
+ if (gitDirLower.endsWith("\\mingw64\\bin")) {
226
+ roots.add(join(gitDir, "..", ".."));
227
+ }
228
+ const bashCandidates = [];
229
+ for (const root of roots) {
230
+ bashCandidates.push(join(root, "bin", "bash.exe"));
231
+ bashCandidates.push(join(root, "usr", "bin", "bash.exe"));
232
+ bashCandidates.push(join(root, "bash.exe"));
233
+ bashCandidates.push(join(root, "mingw64", "bin", "bash.exe"));
234
+ }
235
+ for (const bashPath of bashCandidates) {
236
+ const normalized = normalize(bashPath);
237
+ if (existsSync(normalized)) return normalized;
238
+ }
203
239
  }
204
240
  } catch {
205
241
  }
@@ -1077,7 +1113,7 @@ async function executeClaudeCodeReplyDiskResume(input, sessionManager, allowBypa
1077
1113
 
1078
1114
  // src/tools/claude-code-session.ts
1079
1115
  function executeClaudeCodeSession(input, sessionManager) {
1080
- const toSessionJson = (s) => input.includeSensitive ? sessionManager.toJSON(s) : sessionManager.toPublicJSON(s);
1116
+ const toSessionJson = (s) => input.includeSensitive ? sessionManager.toSensitiveJSON(s) : sessionManager.toPublicJSON(s);
1081
1117
  switch (input.action) {
1082
1118
  case "list": {
1083
1119
  const sessions = sessionManager.list().map((s) => toSessionJson(s));
@@ -1170,7 +1206,7 @@ function executeClaudeCodeConfigure(input, config) {
1170
1206
  }
1171
1207
 
1172
1208
  // src/server.ts
1173
- var SERVER_VERSION = true ? "1.4.0" : "0.0.0-dev";
1209
+ var SERVER_VERSION = true ? "1.6.0" : "0.0.0-dev";
1174
1210
  function createServer(serverCwd, opts) {
1175
1211
  const parsePositiveInt = (value) => {
1176
1212
  if (value === void 0 || value.trim() === "") return void 0;
@@ -1196,30 +1232,36 @@ function createServer(serverCwd, opts) {
1196
1232
  });
1197
1233
  server.tool(
1198
1234
  "claude_code",
1199
- `Start a new Claude Code agent session to perform coding tasks autonomously.
1200
- The agent can read/write files, run commands, search code, and more.
1201
- Returns a sessionId for continuing the conversation later.
1202
- Permission mode defaults to "dontAsk" (non-interactive, safe for MCP).
1203
- By default, loads all local Claude settings (user, project, local) including CLAUDE.md for project context.`,
1235
+ `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.
1236
+ Returns a sessionId that can be passed to claude_code_reply for multi-turn conversations.
1237
+ Defaults: permissionMode="dontAsk" (auto-approves allowed tools without prompting), loads all local Claude settings (user, project, local) including CLAUDE.md.`,
1204
1238
  {
1205
1239
  prompt: z.string().describe("The task or question for Claude Code"),
1206
1240
  cwd: z.string().optional().describe("Working directory (defaults to server cwd)"),
1207
1241
  allowedTools: z.array(z.string()).optional().describe(
1208
- "Tools to auto-approve without prompting. In permissionMode='dontAsk', this effectively acts as a tool whitelist."
1242
+ "List of tool names the agent can use without permission prompts. In the default 'dontAsk' mode, only tools in this list are available. Example: ['Bash', 'Read', 'Write', 'Edit']"
1243
+ ),
1244
+ disallowedTools: z.array(z.string()).optional().describe(
1245
+ "List of tool names the agent is forbidden from using. Takes precedence over allowedTools."
1209
1246
  ),
1210
- disallowedTools: z.array(z.string()).optional().describe("Tool blacklist"),
1211
1247
  tools: z.union([
1212
1248
  z.array(z.string()),
1213
1249
  z.object({
1214
1250
  type: z.literal("preset"),
1215
1251
  preset: z.literal("claude_code")
1216
1252
  })
1217
- ]).optional().describe("Base set of available tools (array of names, or preset)"),
1253
+ ]).optional().describe(
1254
+ "Define the base tool set for the session. Pass an array of tool name strings, or use {type: 'preset', preset: 'claude_code'} for the default Claude Code toolset. allowedTools/disallowedTools further filter on top of this base set."
1255
+ ),
1218
1256
  persistSession: z.boolean().optional().describe(
1219
1257
  "Persist session history to disk (~/.claude/projects). Default: true. Set false to disable persistence."
1220
1258
  ),
1221
- permissionMode: z.enum(PERMISSION_MODES).optional().describe("Permission mode for the session"),
1222
- maxTurns: z.number().int().positive().optional().describe("Maximum agentic turns"),
1259
+ permissionMode: z.enum(PERMISSION_MODES).optional().describe(
1260
+ "Controls how the agent handles tool permissions. 'dontAsk' (default): auto-approve tools in allowedTools without prompting. 'bypassPermissions': skip all permission checks (requires enable_bypass via claude_code_configure). 'plan': require approval before executing."
1261
+ ),
1262
+ maxTurns: z.number().int().positive().optional().describe(
1263
+ "Maximum number of agent reasoning steps. Each step may involve one or more tool calls. Limits how many iterations the agent performs before stopping."
1264
+ ),
1223
1265
  model: z.string().optional().describe("Model to use, e.g. 'claude-sonnet-4-5-20250929'"),
1224
1266
  systemPrompt: z.union([
1225
1267
  z.string(),
@@ -1228,7 +1270,9 @@ By default, loads all local Claude settings (user, project, local) including CLA
1228
1270
  preset: z.literal("claude_code"),
1229
1271
  append: z.string().optional().describe("Additional instructions to append to the preset")
1230
1272
  })
1231
- ]).optional().describe("Custom system prompt (string or preset with optional append)"),
1273
+ ]).optional().describe(
1274
+ "Override the agent's system prompt. Pass a string for full replacement, or use {type: 'preset', preset: 'claude_code', append: '...'} to extend the default Claude Code prompt with additional instructions."
1275
+ ),
1232
1276
  agents: z.record(
1233
1277
  z.string(),
1234
1278
  z.object({
@@ -1242,7 +1286,9 @@ By default, loads all local Claude settings (user, project, local) including CLA
1242
1286
  skills: z.array(z.string()).optional(),
1243
1287
  criticalSystemReminder_EXPERIMENTAL: z.string().optional()
1244
1288
  })
1245
- ).optional().describe("Custom subagent definitions"),
1289
+ ).optional().describe(
1290
+ "Define custom sub-agents that the main agent can delegate tasks to. Each key is the agent name; the value specifies its system prompt, available tools, model, and other constraints."
1291
+ ),
1246
1292
  maxBudgetUsd: z.number().positive().optional().describe("Maximum budget in USD for this session"),
1247
1293
  effort: z.enum(EFFORT_LEVELS).optional().describe(
1248
1294
  "Effort level: 'low' (fast), 'medium' (balanced), 'high' (thorough), 'max' (maximum)"
@@ -1264,13 +1310,17 @@ By default, loads all local Claude settings (user, project, local) including CLA
1264
1310
  timeout: z.number().int().positive().optional().describe("Timeout in milliseconds for this session"),
1265
1311
  pathToClaudeCodeExecutable: z.string().optional().describe("Path to the Claude Code executable"),
1266
1312
  agent: z.string().optional().describe(
1267
- "Main-thread agent name to apply custom agent system prompt, tool restrictions, and model"
1313
+ "Name of a custom agent (defined in 'agents' parameter) to use as the primary agent for this session, applying its system prompt, tool restrictions, and model override."
1268
1314
  ),
1269
1315
  mcpServers: z.record(z.string(), z.record(z.string(), z.unknown())).optional().describe("MCP server configurations (key: server name, value: server config)"),
1270
- sandbox: z.record(z.string(), z.unknown()).optional().describe("Sandbox settings for command execution isolation"),
1316
+ sandbox: z.record(z.string(), z.unknown()).optional().describe(
1317
+ "Sandbox configuration for isolating shell command execution (e.g., Docker container settings). Controls the execution environment for Bash tool calls."
1318
+ ),
1271
1319
  fallbackModel: z.string().optional().describe("Fallback model if the primary model fails or is unavailable"),
1272
1320
  enableFileCheckpointing: z.boolean().optional().describe("Enable file checkpointing to track file changes during the session"),
1273
- includePartialMessages: z.boolean().optional().describe("Include partial/streaming message events in output"),
1321
+ includePartialMessages: z.boolean().optional().describe(
1322
+ "When true, includes intermediate streaming messages in the response (e.g., partial tool outputs as they arrive). Useful for real-time progress monitoring. Default: false."
1323
+ ),
1274
1324
  strictMcpConfig: z.boolean().optional().describe("Enforce strict validation of MCP server configurations"),
1275
1325
  settingSources: z.array(z.enum(["user", "project", "local"])).optional().describe(
1276
1326
  'Control which filesystem settings are loaded. Defaults to ["user", "project", "local"] (loads all settings including ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, and CLAUDE.md). Pass an empty array [] to disable all settings (SDK isolation mode).'
@@ -1309,28 +1359,32 @@ By default, loads all local Claude settings (user, project, local) including CLA
1309
1359
  );
1310
1360
  server.tool(
1311
1361
  "claude_code_reply",
1312
- `Continue an existing Claude Code session with full context preserved.
1313
- Claude remembers all files read, analysis done, and conversation history.`,
1362
+ `Continue an existing Claude Code session by sending a follow-up message. The agent retains full context from previous turns including files read, code analysis, and conversation history. Requires a sessionId returned by a previous claude_code call.
1363
+ Note: When CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1 is set and the in-memory session has expired, the agent can resume from disk-persisted history. Parameters marked "(disk resume fallback)" are only used in this scenario to reconstruct the session.`,
1314
1364
  {
1315
1365
  sessionId: z.string().describe("The session ID to continue (from a previous claude_code call)"),
1316
1366
  prompt: z.string().describe("Follow-up prompt or instruction"),
1317
- forkSession: z.boolean().optional().describe("Fork to a new session (preserves original session state)"),
1367
+ forkSession: z.boolean().optional().describe(
1368
+ "Create a branched copy of this session. The original session remains unchanged; the new session starts with the same context but diverges from this point. Useful for exploring alternative approaches."
1369
+ ),
1318
1370
  timeout: z.number().int().positive().optional().describe("Timeout in milliseconds for this reply"),
1319
1371
  // Optional disk-resume overrides (only used when CLAUDE_CODE_MCP_ALLOW_DISK_RESUME=1
1320
1372
  // and the in-memory session metadata is missing)
1321
- cwd: z.string().optional().describe("Working directory (used only for disk resume when session is missing)"),
1322
- allowedTools: z.array(z.string()).optional().describe("Auto-approved tools (used only for disk resume when session is missing)"),
1323
- disallowedTools: z.array(z.string()).optional().describe("Tool blacklist (used only for disk resume when session is missing)"),
1373
+ cwd: z.string().optional().describe("Working directory (disk resume fallback)"),
1374
+ allowedTools: z.array(z.string()).optional().describe(
1375
+ "Auto-approved tool names (disk resume fallback). See claude_code tool for details."
1376
+ ),
1377
+ disallowedTools: z.array(z.string()).optional().describe("Forbidden tool names (disk resume fallback). See claude_code tool for details."),
1324
1378
  tools: z.union([
1325
1379
  z.array(z.string()),
1326
1380
  z.object({
1327
1381
  type: z.literal("preset"),
1328
1382
  preset: z.literal("claude_code")
1329
1383
  })
1330
- ]).optional().describe("Base set of available tools (array of names, or preset)"),
1384
+ ]).optional().describe("Base tool set (disk resume fallback). See claude_code tool for details."),
1331
1385
  persistSession: z.boolean().optional().describe("Persist session history to disk (~/.claude/projects). Default: true."),
1332
- permissionMode: z.enum(PERMISSION_MODES).optional().describe("Permission mode (used only for disk resume when session is missing)"),
1333
- maxTurns: z.number().int().positive().optional().describe("Maximum agentic turns"),
1386
+ permissionMode: z.enum(PERMISSION_MODES).optional().describe("Permission mode (disk resume fallback). See claude_code tool for details."),
1387
+ maxTurns: z.number().int().positive().optional().describe("Maximum number of agent reasoning steps for this reply."),
1334
1388
  model: z.string().optional().describe("Model to use, e.g. 'claude-sonnet-4-5-20250929'"),
1335
1389
  systemPrompt: z.union([
1336
1390
  z.string(),
@@ -1339,7 +1393,7 @@ By default, loads all local Claude settings (user, project, local) including CLA
1339
1393
  preset: z.literal("claude_code"),
1340
1394
  append: z.string().optional().describe("Additional instructions to append to the preset")
1341
1395
  })
1342
- ]).optional().describe("Custom system prompt (string or preset with optional append)"),
1396
+ ]).optional().describe("Override the agent's system prompt. See claude_code tool for details."),
1343
1397
  agents: z.record(
1344
1398
  z.string(),
1345
1399
  z.object({
@@ -1353,7 +1407,7 @@ By default, loads all local Claude settings (user, project, local) including CLA
1353
1407
  skills: z.array(z.string()).optional(),
1354
1408
  criticalSystemReminder_EXPERIMENTAL: z.string().optional()
1355
1409
  })
1356
- ).optional().describe("Custom subagent definitions"),
1410
+ ).optional().describe("Define custom sub-agents. See claude_code tool for details."),
1357
1411
  maxBudgetUsd: z.number().positive().optional().describe("Maximum budget in USD for this reply"),
1358
1412
  effort: z.enum(EFFORT_LEVELS).optional().describe(
1359
1413
  "Effort level: 'low' (fast), 'medium' (balanced), 'high' (thorough), 'max' (maximum)"
@@ -1372,16 +1426,22 @@ By default, loads all local Claude settings (user, project, local) including CLA
1372
1426
  }),
1373
1427
  z.object({ type: z.literal("disabled") })
1374
1428
  ]).optional().describe("Thinking mode: 'adaptive' (auto), 'enabled' (with budget), or 'disabled'"),
1375
- resumeSessionAt: z.string().optional().describe("Resume only up to and including a specific message UUID (disk resume only)"),
1429
+ resumeSessionAt: z.string().optional().describe(
1430
+ "Resume only up to and including a specific message UUID (disk resume fallback only)"
1431
+ ),
1376
1432
  pathToClaudeCodeExecutable: z.string().optional().describe("Path to the Claude Code executable"),
1377
1433
  agent: z.string().optional().describe(
1378
- "Main-thread agent name to apply custom agent system prompt, tool restrictions, and model"
1434
+ "Name of a custom agent (defined in 'agents') to use as the primary agent. See claude_code tool for details."
1379
1435
  ),
1380
1436
  mcpServers: z.record(z.string(), z.record(z.string(), z.unknown())).optional().describe("MCP server configurations (key: server name, value: server config)"),
1381
- sandbox: z.record(z.string(), z.unknown()).optional().describe("Sandbox settings for command execution isolation"),
1437
+ sandbox: z.record(z.string(), z.unknown()).optional().describe(
1438
+ "Sandbox configuration for isolating shell command execution. See claude_code tool for details."
1439
+ ),
1382
1440
  fallbackModel: z.string().optional().describe("Fallback model if the primary model fails or is unavailable"),
1383
1441
  enableFileCheckpointing: z.boolean().optional().describe("Enable file checkpointing to track file changes during the session"),
1384
- includePartialMessages: z.boolean().optional().describe("Include partial/streaming message events in output"),
1442
+ includePartialMessages: z.boolean().optional().describe(
1443
+ "When true, includes intermediate streaming messages in the response (e.g., partial tool outputs as they arrive). Useful for real-time progress monitoring. Default: false."
1444
+ ),
1385
1445
  strictMcpConfig: z.boolean().optional().describe("Enforce strict validation of MCP server configurations"),
1386
1446
  settingSources: z.array(z.enum(["user", "project", "local"])).optional().describe(
1387
1447
  'Control which filesystem settings are loaded. Defaults to ["user", "project", "local"] (loads all settings including ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, and CLAUDE.md). Pass an empty array [] to disable all settings (SDK isolation mode).'
@@ -1420,12 +1480,12 @@ By default, loads all local Claude settings (user, project, local) including CLA
1420
1480
  );
1421
1481
  server.tool(
1422
1482
  "claude_code_session",
1423
- `Manage Claude Code sessions: list all sessions, get status of a specific session, or cancel a running session.`,
1483
+ `Manage Claude Code sessions. Actions: 'list' returns all sessions with status and metadata; 'get' returns detailed info for a specific session (requires sessionId); 'cancel' terminates a running session (requires sessionId).`,
1424
1484
  {
1425
1485
  action: z.enum(SESSION_ACTIONS).describe("Action to perform: 'list', 'get', or 'cancel'"),
1426
1486
  sessionId: z.string().optional().describe("Session ID (required for 'get' and 'cancel')"),
1427
1487
  includeSensitive: z.boolean().optional().describe(
1428
- "Include sensitive fields (cwd, systemPrompt, agents, additionalDirectories) in responses. Default: false"
1488
+ "When true, includes sensitive fields (cwd, systemPrompt, agents, additionalDirectories) in the response. Requires CLAUDE_CODE_MCP_ALLOW_SENSITIVE_SESSION_DETAILS=1 env var. Default: false."
1429
1489
  )
1430
1490
  },
1431
1491
  async (args) => {
@@ -1461,9 +1521,11 @@ By default, loads all local Claude settings (user, project, local) including CLA
1461
1521
  server.tool(
1462
1522
  "claude_code_configure",
1463
1523
  `Configure the Claude Code MCP server at runtime.
1464
- Actions: enable_bypass (allow bypassPermissions mode), disable_bypass, get_config.`,
1524
+ Actions: 'enable_bypass' allows sessions to use permissionMode='bypassPermissions' (skips all tool permission checks \u2014 use with caution); 'disable_bypass' revokes this ability; 'get_config' returns the current server configuration.`,
1465
1525
  {
1466
- action: z.enum(CONFIGURE_ACTIONS).describe("Configuration action to perform")
1526
+ action: z.enum(CONFIGURE_ACTIONS).describe(
1527
+ "Action to perform: 'enable_bypass' | 'disable_bypass' | 'get_config'. See tool description for details."
1528
+ )
1467
1529
  },
1468
1530
  async (args) => {
1469
1531
  const result = executeClaudeCodeConfigure(args, config);