bashterm-mcp-server 0.2.1 → 0.2.2

package/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.2] - 2026-06-04
+
+### Added
+- 扩展激活时自动配置 Claude Code hook，禁止内置 Bash 工具，引导使用 BashTerm MCP 工具
+- `restoreClaudeCodeDefaultBash` 命令，允许用户一键恢复 Claude Code 默认 Bash 工具
+
+### Fixed
+- 修复 `shell` 参数无效导致终端使用默认 shell 而非指定 shell 的问题
+- 修复 Windows 中文输出乱码问题
+- 修复 Claude Code hook 自动配置 JSON 格式错误
+
+### Changed
+- `autoConfigureClaudeCode` 改为写入用户目录 `~/.claude/settings.json` 而非项目级别配置
+- README 安装指南简化为仅安装 VSCode 扩展即可，零手动配置
+- README 完善 Claude Code Bash 回归与恢复说明
+
 ## [0.2.1] - 2026-06-04
 
 ### Changed

package/CLAUDE.md

@@ -2,15 +2,6 @@
 
 MCP server that runs commands in visible VSCode terminal tabs.
 
-## Terminal Execution
-
-Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool for executing commands. BashTerm runs commands in visible VSCode terminal tabs where the user can see output in real time.
-
-For commands that may take longer than 30 seconds or produce large output, use pull mode:
-1. Call `run` with `waitForCompletion: false`
-2. Call `read` with `offset: -10` to check progress
-3. Repeat until done
-
 ---
 
 ## Release Process

package/README.md

@@ -1,184 +1,122 @@
-# BashTerm
-
-[![中文文档](https://img.shields.io/badge/README-中文-red)](README.zh-CN.md) [![release](https://img.shields.io/npm/v/bashterm-mcp-server?label=release)](https://github.com/1170953489/bashterm-mcp/releases) [![npm version](https://img.shields.io/npm/v/bashterm-mcp-server)](https://www.npmjs.com/package/bashterm-mcp-server)
-
-MCP server that runs shell commands in **visible VSCode terminal tabs** — watch output live, scroll history, interact when needed.
-
-## Key Features
-
-- **Visible Terminals**: Commands run in real VSCode terminal tabs — watch output live, scroll history, interact when needed.
-- **Session Reuse**: `run` automatically reuses idle sessions, creating new terminals only when necessary.
-- **Non-Blocking Execution**: Fire-and-forget with `waitForCompletion: false`, then poll with `read`.
-- **Subagent Isolation**: Tag sessions with `agentId` to keep parallel agent workloads in separate terminals.
-
-## Requirements
-
-- VS Code 1.93+
-- Node.js 20+
-
-## Getting Started
-
-### Claude Code
-
-```bash
-claude mcp add BashTerm -- npx bashterm-mcp-server@latest
-```
-
-### VS Code / Copilot
-
-Add to your `.vscode/mcp.json`:
-
-```json
-{
-  "servers": {
-    "BashTerm": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["bashterm-mcp-server@latest"]
-    }
-  }
-}
-```
-
-<details>
-<summary>Cursor</summary>
-
-Add to your `.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "BashTerm": {
-      "command": "npx",
-      "args": ["-y", "bashterm-mcp-server@latest"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary>Claude Desktop</summary>
-
-Add to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "BashTerm": {
-      "command": "npx",
-      "args": ["-y", "bashterm-mcp-server@latest"]
-    }
-  }
-}
-```
-
-</details>
-
-## Screenshots
-
-![Run command output](docs/images/run_finished.png)
-![Exec permission dialog](docs/images/ask_exec_permission.png)
-![Exec finished](docs/images/exec_finished.png)
-
-## Tools
-
-### Quick Execution
-
-| Tool | Description |
-|------|-------------|
-| `run` | Create (or reuse) a terminal and execute a command in one step. Returns clean output with exit code. |
-
-### Session Management
-
-| Tool | Description |
-|------|-------------|
-| `create` | Open a new visible terminal tab and return a `sessionId`. |
-| `exec` | Run a command in an existing session and capture its output. |
-| `read` | Read session output with offset-based pagination. Use `offset: -N` for tail mode. |
-| `input` | Send text to an interactive process (answer prompts, drive REPLs, confirm actions). |
-| `list` | List active sessions, optionally filtered by `agentId`. |
-| `close` | Close a session and its terminal tab. |
-
-## Usage Patterns
-
-### Simple Command
-
-The `run` tool handles everything — creates a terminal if needed, executes, and returns clean output:
-
-```
-> Run npm test
-```
-
-```
-$ npm test
-PASS src/utils.test.ts (3 tests)
-PASS src/index.test.ts (5 tests)
-
-[exit: 0 | 1243ms | session-abc123]
-```
-
-### Long-Running Process
-
-For builds, deployments, or any command that takes a while:
-
-```
-> Start `npm run build` without waiting, then check progress
-```
-
-The agent launches the command with `waitForCompletion: false` (returns immediately), then polls with `read` (`offset: -10`) until the process finishes.
-
-### Interactive Commands
-
-For commands that need user input:
-
-```
-> Run npm init and answer the prompts
-```
-
-The agent uses `run` to start the command, `read` to check the prompt, and `input` to send responses — driving the interactive process step by step.
-
-### Parallel Agents
-
-Subagents can work in isolated terminals using `agentId`:
-
-```
-> Have one agent run tests while another runs the linter
-```
-
-Each subagent gets its own terminal tagged with its `agentId`, keeping output separate and readable.
-
-## Configuration
-
-The extension reads configuration from VSCode settings under `bashterm-mcp-server.*`:
-
-| Setting | Type | Default | Description |
-|---------|------|---------|-------------|
-| `bashterm-mcp-server.maxSessions` | number | 10 | Maximum concurrent terminal sessions |
-| `bashterm-mcp-server.commandTimeout` | number | 30000 | Default command timeout in ms |
-| `bashterm-mcp-server.maxOutputLines` | number | 5000 | Max lines kept in output buffer per session |
-| `bashterm-mcp-server.idleTimeout` | number | 1800000 | Close idle sessions after this many ms (0 = disabled) |
-| `bashterm-mcp-server.blockedCommands` | string[] | `["rm -rf /"]` | Commands that will be rejected |
-
-## Recommended
-
-LLM agents include a built-in `Bash` tool that runs commands inline, embedding output in the conversation. Prefer BashTerm MCP for visible, scrollable terminal output. Add this to your project's `CLAUDE.md`:
-
-```markdown
-## Terminal Execution
-Prefer the BashTerm MCP tools (`run`, `exec`, `read`, etc.) over the built-in Bash tool.
-BashTerm runs commands in visible VSCode terminal tabs where you can see output in real time.
-For commands over 30 seconds, use pull mode: `run` with `waitForCompletion: false`, then poll with `read` (`offset: -10`).
-```
-
-## Latest Changes (0.2.1)
-
-- **Rename cleanup**: Unified all code, docs, and config references to BashTerm MCP — no more legacy names
-- **Tag fix**: Corrected v0.2.0 tag to point to the proper release commit
-
-See [CHANGELOG.md](CHANGELOG.md) for full history.
-
-## License
-
-MIT
+# BashTerm MCP
+
+[![中文文档](https://img.shields.io/badge/README-中文-red)](README.zh-CN.md) [![release](https://img.shields.io/npm/v/bashterm-mcp-server?label=release)](https://github.com/1170953489/bashterm-mcp/releases) [![npm version](https://img.shields.io/npm/v/bashterm-mcp-server)](https://www.npmjs.com/package/bashterm-mcp-server)
+
+Run AI-generated shell commands in **real, visible VSCode terminals**.
+
+BashTerm MCP turns Claude Code command execution into something you can see, inspect, interrupt, and continue. Instead of hidden shell calls, commands open in normal VSCode terminal tabs with live output, scrollback, interactive input, reusable sessions, and safety controls.
+
+## Why BashTerm MCP
+
+- **Visible by default**: Every command runs in a real VSCode terminal tab, so you can watch builds, tests, logs, and failures as they happen.
+- **Claude Code ready**: The extension registers its MCP server automatically and can guide Claude Code away from the hidden built-in `Bash` tool.
+- **Long-task friendly**: Start commands without blocking the agent, then read output incrementally while the process keeps running.
+- **Interactive when needed**: Answer prompts, drive REPLs, confirm commands, or send Ctrl+C-style input through the same terminal session.
+- **Session reuse**: Keep context in a terminal instead of creating a fresh process for every command.
+- **Parallel-agent isolation**: Use `agentId` to keep multiple AI workers in separate, readable terminals.
+- **Practical guardrails**: Block dangerous command prefixes, restrict working directories, cap output buffers, and auto-close idle sessions.
+- **Safe rollback**: Disable the Claude Code auto-hook or run a restore command to return to Claude Code's default Bash behavior.
+
+## Install
+
+1. Install **BashTerm MCP** from the [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=hcdb.bashterm-mcp-server).
+2. Open VSCode.
+3. Use Claude Code normally.
+
+The extension automatically registers the MCP server through `contributes.mcpServers`, so tools such as `run`, `exec`, `read`, and `input` are available without manual MCP JSON setup.
+
+## Claude Code Integration
+
+BashTerm MCP can write a user-level PreToolUse hook to `~/.claude/settings.json`. That hook blocks Claude Code's built-in hidden `Bash` tool and tells Claude Code to use BashTerm MCP tools instead, keeping command execution visible inside VSCode.
+
+You stay in control:
+
+- Turn it off with `bashterm-mcp-server.autoConfigureClaudeCode`.
+- Restore default Bash with `BashTerm MCP: Restore Claude Code Default Bash` from the Command Palette.
+- Disable or uninstall the extension safely: it removes its own Claude Code hook during deactivation.
+
+## Screenshots
+
+![Run command output](docs/images/run_finished.png)
+![Exec permission dialog](docs/images/ask_exec_permission.png)
+![Exec finished](docs/images/exec_finished.png)
+
+## Common Workflows
+
+### Run a Command
+
+Ask Claude Code:
+
+```text
+Run npm test
+```
+
+BashTerm MCP creates or reuses a visible terminal, runs the command, and returns clean output with the exit code.
+
+### Watch a Long Build
+
+```text
+Start npm run build without waiting, then monitor progress
+```
+
+The agent can launch the command with `waitForCompletion: false`, then poll output with `read` while you watch the same terminal live in VSCode.
+
+### Handle Interactive Prompts
+
+```text
+Run npm init and answer the prompts
+```
+
+The agent can start the process, read the prompt, send input, and continue step by step in the visible terminal.
+
+### Separate Parallel Agents
+
+```text
+Have one agent run tests while another runs the linter
+```
+
+Each agent can receive its own `agentId`, keeping terminal sessions and output streams separate.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `run` | Create or reuse a terminal and run a command in one step. |
+| `create` | Open a visible terminal tab and return a `sessionId`. |
+| `exec` | Run a command in an existing session and capture output. |
+| `read` | Read session output with offset-based pagination or tail mode. |
+| `input` | Send text to an interactive process. |
+| `list` | List active sessions, optionally filtered by `agentId`. |
+| `close` | Close a session and its terminal tab. |
+
+## Configuration
+
+Configure BashTerm MCP from VSCode settings under `bashterm-mcp-server.*`.
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `bashterm-mcp-server.autoConfigureClaudeCode` | boolean | `true` | Automatically configure Claude Code to prefer BashTerm MCP over the built-in `Bash` tool. |
+| `bashterm-mcp-server.blockedCommands` | string[] | `["rm -rf /", "mkfs", "dd if=", ":(){ :|:& };:"]` | Command prefixes that are always rejected. |
+| `bashterm-mcp-server.allowedDirectories` | string[] | `[]` | Allowed working directories. Empty means unrestricted. |
+| `bashterm-mcp-server.defaultTimeoutMs` | number | `30000` | Default command timeout in milliseconds. |
+| `bashterm-mcp-server.maxConcurrentSessions` | number | `10` | Maximum number of concurrent terminal sessions. |
+| `bashterm-mcp-server.maxOutputLines` | number | `10000` | Maximum output lines buffered per session. |
+| `bashterm-mcp-server.idleTimeoutMs` | number | `300000` | Auto-close idle sessions after this many milliseconds. `0` disables it. |
+
+## Requirements
+
+- VSCode 1.99+
+- Node.js 20+
+- Claude Code or another MCP-capable client
+
+## When It Helps Most
+
+BashTerm MCP is especially useful when the agent needs to run commands you care about observing: tests, package installs, dev servers, migrations, scaffolding tools, deploy scripts, and any command that might ask for input or run longer than a few seconds.
+
+## Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for release history.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -1,183 +1,122 @@
-# BashTerm
-
-[![English](https://img.shields.io/badge/README-English-blue)](README.md) [![release](https://img.shields.io/npm/v/bashterm-mcp-server?label=release)](https://github.com/1170953489/bashterm-mcp/releases) [![npm version](https://img.shields.io/npm/v/bashterm-mcp-server)](https://www.npmjs.com/package/bashterm-mcp-server)
-
-在 **VSCode 可见的终端标签页**中执行命令的 MCP 服务器——实时观看输出、滚动历史、按需交互。
-
-## 核心功能
-
-- **可见终端**：命令在真实的 VSCode 终端标签页中运行——实时观看输出、滚动历史、按需交互。
-- **会话复用**：`run` 自动复用空闲会话，仅在必要时创建新终端。
-- **非阻塞执行**：`waitForCompletion: false` 发射后不管，随后用 `read` 轮询。
-- **子代理隔离**：通过 `agentId` 标记会话，将并行代理的工作负载隔离在独立终端中。
-
-## 环境要求
-
-- VS Code 1.93+
-- Node.js 20+
-
-## 快速开始
-
-### Claude Code
-
-```bash
-claude mcp add BashTerm -- npx bashterm-mcp-server@latest
-```
-
-### VS Code / Copilot
-
-在 `.vscode/mcp.json` 中添加：
-
-```json
-{
-  "servers": {
-    "BashTerm": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["bashterm-mcp-server@latest"]
-    }
-  }
-}
-```
-
-<details>
-<summary>Cursor</summary>
-
-在 `.cursor/mcp.json` 中添加：
-
-```json
-{
-  "mcpServers": {
-    "BashTerm": {
-      "command": "npx",
-      "args": ["-y", "bashterm-mcp-server@latest"]
-    }
-  }
-}
-```
-
-</details>
-
-<details>
-<summary>Claude Desktop</summary>
-
-在 `claude_desktop_config.json` 中添加：
-
-```json
-{
-  "mcpServers": {
-    "BashTerm": {
-      "command": "npx",
-      "args": ["-y", "bashterm-mcp-server@latest"]
-    }
-  }
-}
-```
-
-</details>
-
-## 截图
-
-![Run command output](docs/images/run_finished.png)
-![Exec permission dialog](docs/images/ask_exec_permission.png)
-![Exec finished](docs/images/exec_finished.png)
-
-## 工具
-
-### 快速执行
-
-| 工具 | 说明 |
-|------|------|
-| `run` | 一步创建（或复用）终端并执行命令，返回清洁输出和退出码。 |
-
-### 会话管理
-
-| 工具 | 说明 |
-|------|------|
-| `create` | 打开新的可见终端标签页，返回 `sessionId`。 |
-| `exec` | 在已有会话中执行命令并捕获输出。 |
-| `read` | 基于偏移量分页读取会话输出。使用 `offset: -N` 进入 tail 模式。 |
-| `input` | 向交互式进程发送文本（回答提示、驱动 REPL、确认操作）。 |
-| `list` | 列出活动会话，可按 `agentId` 过滤。 |
-| `close` | 关闭会话及其终端标签页。 |
-
-## 使用模式
-
-### 简单命令
-
-`run` 工具处理一切——按需创建终端、执行命令、返回清洁输出：
-
-```
-> 运行 npm test
-```
-
-```
-$ npm test
-PASS src/utils.test.ts (3 tests)
-PASS src/index.test.ts (5 tests)
-
-[exit: 0 | 1243ms | session-abc123]
-```
-
-### 长时间运行
-
-对于构建、部署或其他耗时命令：
-
-```
-> 启动 npm run build 不等待，然后检查进度
-```
-
-代理使用 `waitForCompletion: false` 启动命令（立即返回），然后通过 `read`（`offset: -10`）轮询直到进程完成。
-
-### 交互式命令
-
-对于需要用户输入的命令：
-
-```
-> 运行 npm init 并回答提示
-```
-
-代理使用 `run` 启动命令、`read` 查看提示、`input` 发送响应——逐步驱动交互式进程。
-
-### 并行代理
-
-子代理可以使用 `agentId` 在隔离的终端中工作：
-
-```
-> 让一个代理运行测试，另一个运行代码检查
-```
-
-每个子代理获得独立的终端，标记其 `agentId`，保持输出分离且可读。
-
-## 配置
-
-扩展从 VSCode 设置中读取 `bashterm-mcp-server.*` 配置：
-
-| 设置项 | 类型 | 默认值 | 说明 |
-|--------|------|--------|------|
-| `bashterm-mcp-server.maxSessions` | number | 10 | 最大并发终端会话数 |
-| `bashterm-mcp-server.commandTimeout` | number | 30000 | 默认命令超时（毫秒） |
-| `bashterm-mcp-server.maxOutputLines` | number | 5000 | 每个会话最大缓冲输出行数 |
-| `bashterm-mcp-server.idleTimeout` | number | 1800000 | 空闲会话自动关闭时间（毫秒，0=禁用） |
-| `bashterm-mcp-server.blockedCommands` | string[] | `["rm -rf /"]` | 禁止执行的命令列表 |
-
-## 推荐
-
-LLM 代理内置的 `Bash` 工具将输出内联在对话中，难以翻阅。建议优先使用 BashTerm MCP 在可见终端中执行命令。将以下内容添加到项目的 `CLAUDE.md`：
-
-```markdown
-## 终端执行
-优先使用 BashTerm MCP 工具（`run`、`exec`、`read` 等），而非内置 Bash 工具。
-对于超过 30 秒的命令，使用 pull 模式：`run` 设置 `waitForCompletion: false`，随后用 `read`（`offset: -10`）轮询。
-```
-
-## 最新更新 (0.2.1)
-
-- **重命名清理**：统一所有代码、文档和配置中的项目名称为 BashTerm MCP，无遗留旧名
-- **标签修复**：更正 v0.2.0 标签指向正确的发布 commit
-
-完整历史见 [CHANGELOG.md](CHANGELOG.md)。
-
-## 许可证
-
-MIT
+# BashTerm MCP
+
+[![English](https://img.shields.io/badge/README-English-blue)](README.md) [![release](https://img.shields.io/npm/v/bashterm-mcp-server?label=release)](https://github.com/1170953489/bashterm-mcp/releases) [![npm version](https://img.shields.io/npm/v/bashterm-mcp-server)](https://www.npmjs.com/package/bashterm-mcp-server)
+
+让 AI 生成的 shell 命令在 **真实可见的 VSCode 终端**里运行。
+
+BashTerm MCP 把 Claude Code 的命令执行变成你能看见、能检查、能中断、能继续交互的过程。不再是隐藏的后台 Bash 调用，而是普通 VSCode 终端标签页：实时输出、历史滚动、交互输入、会话复用和安全控制都在你眼前。
+
+## 为什么选择 BashTerm MCP
+
+- **默认可见**：每条命令都在真实 VSCode 终端标签页中运行，测试、构建、日志和报错都能实时看到。
+- **开箱支持 Claude Code**：扩展会自动注册 MCP server，并可引导 Claude Code 使用 BashTerm MCP 替代隐藏的内置 `Bash`。
+- **适合长任务**：命令可以非阻塞启动，进程持续运行时再增量读取输出。
+- **支持交互命令**：可以回答提示、驱动 REPL、确认操作，或向同一个终端会话继续发送输入。
+- **会话复用**：复用已有终端上下文，减少每条命令都新开进程带来的割裂感。
+- **并行代理隔离**：通过 `agentId` 让多个 AI worker 使用不同终端，输出清晰不串台。
+- **实用安全边界**：支持危险命令前缀拦截、工作目录限制、输出缓冲上限和空闲会话自动关闭。
+- **可安全回退**：可关闭 Claude Code 自动 hook，或一键恢复 Claude Code 默认 Bash 行为。
+
+## 安装
+
+1. 从 [VSCode Marketplace](https://marketplace.visualstudio.com/items?itemName=hcdb.bashterm-mcp-server) 安装 **BashTerm MCP**。
+2. 打开 VSCode。
+3. 正常使用 Claude Code。
+
+扩展会通过 `contributes.mcpServers` 自动注册 MCP server，`run`、`exec`、`read`、`input` 等工具无需手写 MCP JSON 配置即可使用。
+
+## Claude Code 集成
+
+BashTerm MCP 可以向用户级 `~/.claude/settings.json` 写入 PreToolUse hook。这个 hook 会拦截 Claude Code 隐藏的内置 `Bash` 工具，并提示 Claude Code 改用 BashTerm MCP 工具，让命令执行保持在 VSCode 可见终端中。
+
+控制权始终在用户手里：
+
+- 关闭 `bashterm-mcp-server.autoConfigureClaudeCode` 即可停用自动 hook。
+- 在命令面板执行 `BashTerm MCP: Restore Claude Code Default Bash` 可恢复默认 Bash。
+- 直接禁用或卸载扩展也安全：扩展停用时会移除自己写入的 Claude Code hook。
+
+## 截图
+
+![Run command output](docs/images/run_finished.png)
+![Exec permission dialog](docs/images/ask_exec_permission.png)
+![Exec finished](docs/images/exec_finished.png)
+
+## 常见使用场景
+
+### 运行普通命令
+
+告诉 Claude Code：
+
+```text
+运行 npm test
+```
+
+BashTerm MCP 会创建或复用一个可见终端，执行命令，并返回清洁输出和退出码。
+
+### 观察长时间构建
+
+```text
+启动 npm run build，不要等待结束，然后持续查看进度
+```
+
+代理可以用 `waitForCompletion: false` 启动命令，再通过 `read` 轮询输出；同时你也能在 VSCode 终端里实时观察同一个进程。
+
+### 处理交互式提示
+
+```text
+运行 npm init 并回答提示
+```
+
+代理可以启动进程、读取提示、发送输入，然后一步步驱动交互式命令。
+
+### 隔离并行代理
+
+```text
+让一个代理跑测试，另一个代理跑 lint
+```
+
+每个代理都可以带上自己的 `agentId`，终端会话和输出流彼此分离。
+
+## 工具列表
+
+| 工具 | 功能 |
+|------|------|
+| `run` | 创建或复用终端，并一步执行命令。 |
+| `create` | 打开可见终端标签页并返回 `sessionId`。 |
+| `exec` | 在已有会话中执行命令并捕获输出。 |
+| `read` | 按偏移量分页读取输出，或进入 tail 模式。 |
+| `input` | 向交互式进程发送文本。 |
+| `list` | 列出活动会话，可按 `agentId` 过滤。 |
+| `close` | 关闭会话及其终端标签页。 |
+
+## 配置
+
+可在 VSCode 设置中配置 `bashterm-mcp-server.*`。
+
+| 设置项 | 类型 | 默认值 | 说明 |
+|--------|------|--------|------|
+| `bashterm-mcp-server.autoConfigureClaudeCode` | boolean | `true` | 自动配置 Claude Code，使其优先使用 BashTerm MCP 而不是内置 `Bash`。 |
+| `bashterm-mcp-server.blockedCommands` | string[] | `["rm -rf /", "mkfs", "dd if=", ":(){ :|:& };:"]` | 始终拒绝执行的命令前缀。 |
+| `bashterm-mcp-server.allowedDirectories` | string[] | `[]` | 允许的工作目录。为空表示不限制。 |
+| `bashterm-mcp-server.defaultTimeoutMs` | number | `30000` | 默认命令超时时间，单位毫秒。 |
+| `bashterm-mcp-server.maxConcurrentSessions` | number | `10` | 最大并发终端会话数。 |
+| `bashterm-mcp-server.maxOutputLines` | number | `10000` | 每个会话最多缓冲的输出行数。 |
+| `bashterm-mcp-server.idleTimeoutMs` | number | `300000` | 空闲会话自动关闭时间，单位毫秒。`0` 表示禁用。 |
+
+## 环境要求
+
+- VSCode 1.99+
+- Node.js 20+
+- Claude Code 或其它支持 MCP 的客户端
+
+## 适合什么场景
+
+BashTerm MCP 特别适合那些你希望亲眼观察的命令：测试、包安装、开发服务器、数据库迁移、脚手架工具、部署脚本，以及任何可能需要输入或运行时间较长的命令。
+
+## 更新日志
+
+完整历史见 [CHANGELOG.md](CHANGELOG.md)。
+
+## 许可证
+
+MIT

package/dist/extension.js

@@ -5389,7 +5389,7 @@ var zodToJsonSchema = (schema, options) => {
 };
 
 // package.json
-var version = "0.2.1";
+var version = "0.2.2";
 
 // src/mcp/tools/schemas.ts
 var coerceBoolean = external_exports.preprocess(
@@ -5980,6 +5980,29 @@ function generateCommandId() {
   return `cmd-${v4_default().slice(0, 8)}`;
 }
 
+// src/utils/exec-options.ts
+function buildExecOptions(params) {
+  return {
+    cwd: params.cwd,
+    timeout: params.timeoutMs,
+    windowsHide: true,
+    encoding: params.isWin ? null : "utf8",
+    shell: params.shell
+  };
+}
+function detectShellEncoding(isWin, shell) {
+  if (!isWin) return "utf-8";
+  if (!shell) return "gbk";
+  const lower = shell.toLowerCase();
+  if (/(^|[\/\\])(ba|z|fi|da|k)?sh(\.exe)?$/i.test(lower) || lower.includes("wsl")) {
+    return "utf-8";
+  }
+  if (lower.includes("pwsh")) {
+    return "utf-8";
+  }
+  return "gbk";
+}
+
 // src/terminal/session.ts
 var TerminalSession = class {
   sessionId;
@@ -6094,12 +6117,12 @@ var TerminalSession = class {
     return new Promise((resolve2) => {
       let resolved = false;
       const isWin = process.platform === "win32";
-      const options = {
+      const options = buildExecOptions({
         cwd: this.cwd,
-        timeout: timeoutMs,
-        windowsHide: true,
-        encoding: isWin ? null : "utf8"
-      };
+        timeoutMs,
+        shell: this.shell,
+        isWin
+      });
       const child = cp.exec(command, options, (error, stdout, stderr) => {
         if (resolved) return;
         resolved = true;
@@ -6107,7 +6130,8 @@ var TerminalSession = class {
         let outStr;
         let errStr;
         if (isWin) {
-          const td = new import_util4.TextDecoder("gbk");
+          const textEncoding = detectShellEncoding(isWin, this.shell);
+          const td = new import_util4.TextDecoder(textEncoding);
           outStr = stdout ? td.decode(stdout) : "";
           errStr = stderr ? td.decode(stderr) : "";
         } else {
@@ -6431,6 +6455,7 @@ var SessionManager = class {
 var ipcServer;
 var sessionManager;
 var statusBarItem;
+var CLAUDE_CODE_BASH_BLOCK_MESSAGE = "Please use BashTerm MCP tools (run / exec / read) instead of the built-in Bash tool. These commands execute visibly in VSCode terminal tabs.";
 function getSocketPath() {
   const tmpDir = os.tmpdir();
   const crypto3 = require("crypto");
@@ -6438,12 +6463,14 @@ function getSocketPath() {
   const hash = crypto3.createHash("md5").update(workspace4).digest("hex").slice(0, 8);
   const isWin = process.platform === "win32";
   const socketPath = isWin ? path2.join("\\\\?\\pipe", `bashterm-mcp-${hash}`) : path2.join(tmpDir, `bashterm-mcp-${hash}.sock`);
-  const discoveryPath = path2.join(tmpDir, "bashterm-mcp.discovery");
+  return socketPath;
+}
+function publishSocketPath(socketPath) {
+  const discoveryPath = path2.join(os.tmpdir(), "bashterm-mcp.discovery");
   try {
     fs.writeFileSync(discoveryPath, socketPath);
   } catch {
   }
-  return socketPath;
 }
 function cleanupSocket(socketPath) {
   if (process.platform === "win32") return;
@@ -6454,9 +6481,136 @@ function cleanupSocket(socketPath) {
   } catch {
   }
 }
+function getClaudeCodeSettingsPath() {
+  const claudeDir = path2.join(os.homedir(), ".claude");
+  return {
+    claudeDir,
+    settingsPath: path2.join(claudeDir, "settings.json")
+  };
+}
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function isLegacyBashTermClaudeCodeHook(value) {
+  if (!isRecord(value) || value.matcher !== "Bash") return false;
+  const legacyMessage = value.message;
+  return value.action === "block" && typeof legacyMessage === "string" && legacyMessage.includes("BashTerm MCP");
+}
+function isCurrentBashTermClaudeCodeHook(value) {
+  if (!isRecord(value) || value.matcher !== "Bash") return false;
+  if (!Array.isArray(value.hooks)) return false;
+  return value.hooks.some(
+    (handler) => isRecord(handler) && handler.type === "command" && typeof handler.command === "string" && handler.command.includes("BashTerm MCP")
+  );
+}
+function isBashTermClaudeCodeHook(value) {
+  return isLegacyBashTermClaudeCodeHook(value) || isCurrentBashTermClaudeCodeHook(value);
+}
+function readClaudeCodeSettings(settingsPath) {
+  if (!fs.existsSync(settingsPath)) return {};
+  try {
+    const raw = fs.readFileSync(settingsPath, "utf-8");
+    return JSON.parse(raw);
+  } catch {
+    log("Failed to parse .claude/settings.json");
+    return {};
+  }
+}
+function writeClaudeCodeSettings(claudeDir, settingsPath, settings) {
+  if (!fs.existsSync(claudeDir)) {
+    fs.mkdirSync(claudeDir, { recursive: true });
+  }
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+}
+function createClaudeCodeBashBlockHook() {
+  const blockCommand = process.platform === "win32" ? `powershell.exe -NoProfile -ExecutionPolicy Bypass -Command "[Console]::Error.WriteLine('${CLAUDE_CODE_BASH_BLOCK_MESSAGE}'); exit 2"` : `sh -c 'printf "%s\\n" "${CLAUDE_CODE_BASH_BLOCK_MESSAGE}" >&2; exit 2'`;
+  return {
+    matcher: "Bash",
+    hooks: [
+      {
+        type: "command",
+        command: blockCommand
+      }
+    ]
+  };
+}
+function autoConfigureClaudeCode() {
+  const { claudeDir, settingsPath } = getClaudeCodeSettingsPath();
+  const settings = readClaudeCodeSettings(settingsPath);
+  const hooks = isRecord(settings.hooks) ? settings.hooks : {};
+  const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+  const preToolUse = existingPreToolUse.filter(
+    (h) => isRecord(h) && !isLegacyBashTermClaudeCodeHook(h)
+  );
+  const alreadyConfigured = preToolUse.some(isCurrentBashTermClaudeCodeHook);
+  const needsCleanup = preToolUse.length !== existingPreToolUse.length;
+  if (alreadyConfigured && !needsCleanup) return;
+  if (!alreadyConfigured) {
+    preToolUse.push(createClaudeCodeBashBlockHook());
+  }
+  hooks.PreToolUse = preToolUse;
+  settings.hooks = hooks;
+  try {
+    writeClaudeCodeSettings(claudeDir, settingsPath, settings);
+    log("Auto-configured .claude/settings.json: Bash tool blocked, BashTerm MCP preferred");
+  } catch (err) {
+    logError("Failed to auto-configure .claude/settings.json", err);
+  }
+}
+function restoreClaudeCodeDefaultBash() {
+  const { claudeDir, settingsPath } = getClaudeCodeSettingsPath();
+  if (!fs.existsSync(settingsPath)) return false;
+  const settings = readClaudeCodeSettings(settingsPath);
+  if (!isRecord(settings.hooks)) return false;
+  const hooks = settings.hooks;
+  const existingPreToolUse = Array.isArray(hooks.PreToolUse) ? hooks.PreToolUse : [];
+  const preToolUse = existingPreToolUse.filter((hook) => !isBashTermClaudeCodeHook(hook));
+  if (preToolUse.length === existingPreToolUse.length) return false;
+  if (preToolUse.length > 0) {
+    hooks.PreToolUse = preToolUse;
+  } else {
+    delete hooks.PreToolUse;
+  }
+  if (Object.keys(hooks).length > 0) {
+    settings.hooks = hooks;
+  } else {
+    delete settings.hooks;
+  }
+  try {
+    writeClaudeCodeSettings(claudeDir, settingsPath, settings);
+    log("Restored Claude Code default Bash by removing BashTerm MCP hook");
+    return true;
+  } catch (err) {
+    logError("Failed to restore Claude Code default Bash", err);
+    return false;
+  }
+}
 function activate(context) {
   const outputChannel2 = initLogger();
   log("BashTerm MCP extension activating...");
+  const applyClaudeCodePreference = () => {
+    const autoConfigureClaude = vscode4.workspace.getConfiguration("bashterm-mcp-server").get("autoConfigureClaudeCode", true);
+    if (autoConfigureClaude) {
+      autoConfigureClaudeCode();
+    } else {
+      restoreClaudeCodeDefaultBash();
+    }
+  };
+  applyClaudeCodePreference();
+  context.subscriptions.push(
+    vscode4.workspace.onDidChangeConfiguration((event) => {
+      if (event.affectsConfiguration("bashterm-mcp-server.autoConfigureClaudeCode")) {
+        applyClaudeCodePreference();
+      }
+    })
+  );
+  context.subscriptions.push(
+    vscode4.commands.registerCommand("bashterm-mcp-server.restoreClaudeCodeDefaultBash", () => {
+      const restored = restoreClaudeCodeDefaultBash();
+      const message = restored ? "Claude Code default Bash restored. Restart Claude Code to apply the change." : "No BashTerm MCP Claude Code hook was found.";
+      void vscode4.window.showInformationMessage(message);
+    })
+  );
   sessionManager = new SessionManager();
   statusBarItem = vscode4.window.createStatusBarItem(
     vscode4.StatusBarAlignment.Left,
@@ -6474,6 +6628,7 @@ function activate(context) {
   });
   const handleMcpRequest = createMcpRequestHandler(sessionManager);
   const socketPath = getSocketPath();
+  publishSocketPath(socketPath);
   cleanupSocket(socketPath);
   ipcServer = net.createServer((connection) => {
     log("IPC client connected");
@@ -6543,6 +6698,7 @@ async function handleIpcRequest(request, connection, handleMcpRequest) {
 }
 function deactivate() {
   log("BashTerm MCP extension deactivating...");
+  restoreClaudeCodeDefaultBash();
   if (ipcServer) {
     ipcServer.close();
     ipcServer = void 0;

package/package.json

@@ -2,7 +2,7 @@
   "name": "bashterm-mcp-server",
   "displayName": "BashTerm MCP",
   "description": "MCP server that executes commands in visible VSCode terminal tabs. Supports Windows, macOS and Linux.",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "publisher": "hcdb",
   "license": "MIT",
   "author": "hcdb",
@@ -32,13 +32,20 @@
     "Other"
   ],
   "activationEvents": [
-    "onStartupFinished"
+    "onStartupFinished",
+    "onCommand:bashterm-mcp-server.restoreClaudeCodeDefaultBash"
   ],
   "main": "./dist/extension.js",
   "bin": {
     "bashterm-mcp-server": "dist/mcp-entry.js"
   },
   "contributes": {
+    "commands": [
+      {
+        "command": "bashterm-mcp-server.restoreClaudeCodeDefaultBash",
+        "title": "BashTerm MCP: Restore Claude Code Default Bash"
+      }
+    ],
     "mcpServers": {
       "bashterm-mcp-server": {
         "type": "stdio",
@@ -51,6 +58,11 @@
     "configuration": {
       "title": "BashTerm MCP",
       "properties": {
+        "bashterm-mcp-server.autoConfigureClaudeCode": {
+          "type": "boolean",
+          "default": true,
+          "description": "Automatically configure Claude Code to block the built-in Bash tool and prefer BashTerm MCP tools"
+        },
         "bashterm-mcp-server.blockedCommands": {
           "type": "array",
           "items": {
@@ -122,6 +134,6 @@
     "eslint": "^8.57.0",
     "prettier": "^3.2.0",
     "typescript": "^5.4.0",
-    "vitest": "^1.6.0"
+    "vitest": "^3.2.6"
   }
 }

package/server.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.hcdb/bashterm-mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "BashTerm MCP — execute commands in visible VSCode terminal tabs with output capture and session reuse.",
   "author": "hcdb",
   "license": "MIT",
@@ -14,7 +14,7 @@
     {
       "registryType": "npm",
       "identifier": "bashterm-mcp-server",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "transport": {
         "type": "stdio"
       }