opencode-idea 0.0.12 → 0.0.14

package/README.md

@@ -48,10 +48,12 @@ setup(启动, 每项目一次):
   2. 触发成功 → 把该错误改写为"已重连 / 已重新打开,请重试",模型同一回合重试;失败 → 保持原错误
 
 后台探活(心跳;仅"已标记 + 桥已注册"的项目):
-  1. 每 5s 探测 IDE 端口(/stream);连续 2 次不通 →
+  1. 每 5s 探测一次 IDE 端口(/stream);探一次不通 →
   2. **注销 `idea` MCP**:杀掉僵尸桥子进程 + 从注册表移除 `idea_*` 工具
      (→ 模型调不到,也就不会挂起;这一步是"从根上避免挂起"的关键)
-  3. 锁存 `needRebuild = true`(不会因端口恢复而清,因为桥不会自愈)
+  3. 锁存 `needRebuild = true`(不会因端口恢复而清,因为桥不会自愈);
+     同理,任一请求若发现「本会话曾有工具、本请求没有」也置同一锁存——
+     端口还在答、只是桥子进程死了这类情况,心跳看不到
   4. 下一条用户消息:纯内存读到锁存 → 自动重跑接入流程(IDE 不在则 `open -a` 拉起),成功后清锁存
      —— 全程静默,用户无感
   ※ 这是**每个 Location(项目)各跑一份**探活;IDE 只有一个,所以所有项目的桥几乎同时被注销、再各自重建
@@ -124,14 +126,33 @@ IDE MCP 只能 **查**(`get_run_configurations`)和 **执行**(`execute_run_conf
 `setup` 时(读回标记)就会注册。未标记的项目不受影响。文档放在 `skills/<id>/SKILL.md`(每个 skill 一个目录,`name` /
 `description` 走 YAML frontmatter),由 `src/skill/loader.js` 扫描加载 —— **加新 skill 只需加一个目录,不用改代码**。
 
+## Standalone 模式纪律 (skill)
+
+本机直跑应用的**项目级纪律**由 `idea-standalone` skill 固化:它为项目生成/维护一份 rule,落在项目根
+**`.opencode/rules/idea-standalone.md`**,四段结构固定 ——
+
+1. **什么是 standalone 模式**:**standalone = 通过 IDEA 启动**(每个应用的入口是 IDEA run configuration),应用在本机进程
+   直跑(不容器化、不部署),只启动其中一部分是常态;启停一律由用户在 IDEA 里手动完成,AI 不得代为启停(含经
+   `idea_execute_run_configuration`),判断需要重启时先取得用户明确授权;
+2. **启动哪些应用**:一行一个应用,启动路径**只能是 IDEA run configuration**(配置名必须能在 `idea_get_run_configurations`
+   里查到;缺配置先走 `idea-run-config` skill 建 `.run/*.run.xml`),端口与被依赖的先后顺序一并写明;
+3. **热重载矩阵**:逐应用标"是 / 否" —— 带 HMR 的 dev server 改动后**不用**提示重启;`go run .` 这类无热重载的进程改动后
+   **必须**显式点名「需要重启 <应用>」,不得在未提示的情况下宣称"改完可验证";
+4. **项目补充条款**:文件写入位置、测试纪律、访问归属、dev 模式特有限制等,按用户给的条款逐条续写、保留原意。
+
+事实一律先查后写:配置名来自 `idea_get_run_configurations`,热重载列来自运行方式,端口读不到就问用户 —— 不猜。
+
 ## 项目命令执行 (IDE 终端)
 
-跑项目相关的命令时,模型使用 **`idea_execute_terminal_command`**,而不是 OpenCode 原生 shell。判据是**命令是否依赖项目的
-工具链 / 运行时 / 依赖环境**,而不是语言或工具名:
+跑项目相关的命令时,模型使用 **`idea_execute_terminal_command`**,而不是 OpenCode 原生 shell。判据是**白名单**:命令用于本项目
+自身的构建 / 测试 / 运行,且首个可执行文件命中下表,才走 IDE 终端;其余一律走原生 shell。
 
-- **走 IDE 终端**:任何会调用项目工具链的命令 —— Java / Python / Node / Go 的运行时,以及 Maven / Gradle、uv / pip /
-  poetry、cargo、bundler、make / cmake、包管理器、构建、测试、代码生成等。
-- **走原生 shell**:纯操作系统级的通用命令(`ls` / `cat` / `cp` / `mkdir` / `git` 等)。
+- **Node / 前端**(`package.json`):`node` / `npm` / `npx` / `pnpm` / `yarn` / `vite` / `webpack` / `esbuild` / `tsc` /
+  `jest` / `vitest`。
+- **Java**(`pom.xml` / `build.gradle`):`java` / `javac` / `mvn` / `mvnw` / `gradle` / `gradlew`。
+- **Python**(`pyproject.toml` / `requirements.txt`):`python` / `python3` / `pip` / `pip3` / `uv` / `poetry` / `pytest`。
+- **Go**(`go.mod`):`go` / `gofmt` / `golangci-lint`。
+- 白名单未覆盖的语言暂走原生 shell,遇到后再补进上表。
 
 原因:
 
@@ -253,7 +274,7 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
         "mcpProbeTimeoutMs": 1000, // 单个 MCP 端口的短探测超时
         "executionTimeoutMs": 600000, // 单次 idea_* 工具调用硬上限;默认 10 分钟(OpenCode 默认 12 小时)
         "heartbeatIntervalMs": 5000, // 后台端口探活间隔
-        "heartbeatFailures": 2, // 连续失败几次后注销 idea MCP
+        "heartbeatFailures": 1, // 探活失败几次后注销 idea MCP(默认一次即注销)
         "feedback": "message", // "message"(默认,会话通知,AI 只回"收到")| false(静默)
       },
     },
@@ -275,7 +296,7 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
 | `mcpProbeTimeoutMs`   | `number`             | `1000`      | 单个 MCP 端口的短探测超时                                                               |
 | `executionTimeoutMs`  | `number`             | `600000`    | 单次 `idea_*` 工具调用的硬上限(毫秒);防止桥挂起后无限等待(OpenCode 默认 12 小时)        |
 | `heartbeatIntervalMs` | `number`             | `5000`      | 后台 IDE 端口探活间隔(毫秒);仅"已标记 + 桥已注册"的项目有效                             |
-| `heartbeatFailures`   | `number`             | `2`         | 连续探活失败几次后注销 `idea` MCP(杀僵尸桥 + 移除工具),下一条消息自动重建               |
+| `heartbeatFailures`   | `number`             | `1`         | 探活失败几次后注销 `idea` MCP(杀僵尸桥 + 移除工具),下一条消息自动重建                   |
 | `feedback`            | `"message" \| false` | `"message"` | 结果反馈:`message` 会话通知(用户可见,AI 只回"收到");`false` 静默                        |
 
 ## 行为
@@ -288,9 +309,13 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
   僵尸桥只要重跑一次命令就能恢复。命令返回即可用;`/close-in-idea` 注销 `idea` + 删标记 + 清环境。
 - **`context` 钩子是请求的纯函数**:按「每次模型调用」触发 (含工具续跑),只看本次请求自带的工具快照 —— 有 `idea_*` 就剥离隐藏
   工具并注入引导;没有则只在项目被标记时给恢复提示。该钩子本身**不做任何 I/O**(只看内存缓存),也不订阅任何事件。
-- **后台心跳(仅"已标记 + 桥已注册"的项目)**:每 `heartbeatIntervalMs`(默认 5s)探一次 IDE 端口;连续 `heartbeatFailures`
-  (默认 2)次不通就**注销 `idea` MCP** —— 杀掉僵尸桥子进程 + 移除 `idea_*` 工具,于是模型**调不到、也就不会挂起** —— 并锁存
+- **后台心跳(仅"已标记 + 桥已注册"的项目)**:每 `heartbeatIntervalMs`(默认 5s)探一次 IDE 端口;`heartbeatFailures`
+  (默认 1)次不通就**注销 `idea` MCP** —— 杀掉僵尸桥子进程 + 移除 `idea_*` 工具,于是模型**调不到、也就不会挂起** —— 并锁存
   `needRebuild`。下一条用户消息在 `prompt` 钩子里读到锁存 → 自动重跑接入流程(IDE 不在则 `open -a` 拉起),成功后清锁存。**全程静默**。
+  锁存还有**第二个来源**:`context` 钩子(每个 agent-loop step 都跑)发现「本会话见过 `idea_*` 工具、本请求却没有」也置位 ——
+  心跳只认"端口不通",而桥子进程自己死了、或一次失败的重连把注册拆掉(`reconcileOnce` 先拆后建,建不起来就只剩拆)时端口可能还是通的,
+  这两种情况以前**不会置锁存**,于是下一条消息什么都不做,只能手动 `/open-in-idea`。工具缺失时注入的恢复引导也改为**明确禁止**
+  调用 `idea_*`(此前复用"重试一次"的文案,反而诱导模型去调一个不在工具表里的工具,得到 `No tool named ... available`)。
   探活是**每个 Location(项目)各一份**;IDE 只有一个,所以 IDE 一挂、所有项目的桥几乎同时被注销,再由各自的消息触发重建。
 - **失败触发的自动接入(仅被标记项目)**:`tool.execute.after` 钩子监听 `idea_*` 工具报错并**分类**:
   - IDE MCP 不可用(掉了)→ 重跑 `/open-in-idea` 的接入流程;
@@ -327,7 +352,8 @@ export { default } from "/Users/yutao/Projects/opencode-idea/src/index.js";
   以及**调用进行中**IDE 挂(在 IDE 里跑 `sleep 120` 时 `kill` 掉 IDEA),桥都只在 stderr 打一行错误(`SseClientTransport is closed!` /
   `Request timeout has expired`),**stdout 一个字节都不回**。而且**重开 IDEA 也不会自愈**(实测:重开 IDEA 后连续探测 5 分钟仍全部 TIMEOUT);
   OpenCode 依旧显示 connected,`refresh`/`reload` 只会 `reconcile`,配置没变就跳过,不会重启它。所以:
-  - **后台心跳(见上)自动兜底**:5s 探活、连续 2 次不通就注销 `idea`(杀僵尸桥 + 移除工具),下一条消息自动重建 —— 常态下**不需要用户手动做什么**;
+  - **后台心跳(见上)自动兜底**:5s 探活、探一次不通就注销 `idea`(杀僵尸桥 + 移除工具);此外任一请求发现工具缺失也会置锁存,
+    两种情况都是下一条消息自动重建 —— 常态下**不需要用户手动做什么**;
   - 手动重建仍可用:重开 IDEA 后再执行一次 `/open-in-idea`(先注销旧 `idea`、再重新注册);
   - 插件给 `idea` server 配 `executionTimeoutMs`(默认 **10 分钟**)作为硬上限:兜住"心跳尚未触发、工具已在途"的那次挂起,不再沿用 OpenCode 默认的 12 小时;
   - "IDE 被关掉 → 工具挂起"这类**不会**走工具失败分类(没有 error);能自动分类处理的是"IDE 在、项目没打开"和"server 掉了(启动即失败)"。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-idea",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "OpenCode plugin that connects to JetBrains IDE MCP servers and prefers IDE tools when the current project is open in the IDE",
   "main": "src/index.js",
   "type": "module",

package/skills/idea-standalone/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: idea-standalone
+description: "为项目生成/维护 standalone(经 IDEA 启动、本机进程直跑)模式的纪律 rule,写在项目根 `.opencode/rules/idea-standalone.md`。当用户要做 standalone 规范、要固化「本机跑哪几个应用」「哪些应用热重载、哪些改了必须重启」「AI 能不能启停本机进程」这类项目级纪律时使用。产出必须写清四段:standalone 是什么、standalone 下经 IDEA run configuration 启动哪些应用、逐应用的热重载与重启提示纪律、以及用户补充的其它条款。"
+---
+
+# Standalone 模式纪律 rule 生成器
+
+## 产出物
+
+一份 **项目级 rule**:`<项目根>/.opencode/rules/idea-standalone.md`,把这个项目在 **本机 standalone 模式**下怎么跑、AI
+能做什么不能做什么固化下来。
+
+- 位置固定:`.opencode/rules/`(项目级规则目录),文件名 `idea-standalone.md`。
+- frontmatter 照抄项目里既有 rule 的格式 (`description` + `alwaysApply: true`)。
+- 只对这个项目生效; **不写**全局规则目录 (`~/.config/opencode/rules/`)。
+
+## 四段结构 (缺一不可)
+
+### 第一段:什么是 standalone 模式
+
+**standalone = 通过 IDEA 启动** —— 应用在本机进程直跑,不容器化、不部署到远端。给"本项目在本机的运行形态"下定义,至少覆盖:
+
+- **通过 IDEA 启动**:每个应用的启动入口就是 IDEA 的 run configuration(Run / Debug),不是手搓命令行。
+- **应用在本机进程直跑**:不容器化、不部署到远端。本机 **不跑**什么也要写明 (例如需要 GPU 的服务、或本机直连的远端数据库)。
+- **只启动其中一部分是常态** —— standalone 不要求所有应用都起来,用户可能只开一两个。
+- **启停一律由用户在 IDEA 手动完成**:AI 不得代为启停本机进程 —— 包括 `go run` / `pnpm dev` / `uvicorn` /
+  `python -m ...` 这类起进程、`kill` / `pkill` 业务进程,以及经 `idea_execute_run_configuration` 启停。AI 若判断需要重启,
+  **先向用户说明并取得明确授权**,绝不自行执行。
+- **与部署链纪律互不构成许可**:standalone 的禁令不适用于部署流程,部署链的步骤也不构成"可以动本机进程"的许可 —— 两阶段纪律互相独立。
+
+### 第二段:standalone 下启动哪些应用 (必须经 IDEA run configuration)
+
+表格,一行一个应用:
+
+| 应用 | run configuration | 目录 | 端口 | 说明 |
+|------|-------------------|------|------|------|
+
+要点:
+
+- `run configuration` 列 **必须是 `idea_get_run_configurations` 里真实存在的名字**(不凭印象写);缺配置时先用
+  `idea-run-config` skill 建项目级 `.run/*.run.xml`,不要手搓启动命令。
+- **启动路径只能是 IDEA run configuration**:不写 `pnpm dev &`、`nohup ... &` 这类后台命令,也不建议用户这么干。
+- 端口写清"固定 / 默认 / 被占用即启动失败"; **哪个应用必须先起来**也要写 (例如前端 dev server 的 proxy 指向本机后端)。
+- 端口读不到 (配置里没有、也没写在项目配置里)就 **问用户**,不要编。
+
+### 第三段:热重载矩阵 + 改代码后要不要提醒重启
+
+逐应用写清 **是 / 不是**热重载,以及对应的提醒纪律:
+
+| 应用                                                  | 热重载 | AI 改代码后                                           |
+|-------------------------------------------------------|--------|-------------------------------------------------------|
+| 带 HMR 的 dev server(如 Vite)                         | 是     | 不提醒重启                                            |
+| 编译型 / 无热重载进程(如 `go run .`、`python -m ...`) | 否     | **必须**在回复里显式点名「需要重启 <应用>」并说明原因 |
+| 只能跑在远端、本机起不来的服务                        | 不适用 | 本机无法验证,按部署链部署后再验证                     |
+
+铁律:
+
+- 非热重载的应用改动后, **不得**在没有提示的情况下宣称"改动完成 / 可以去验证了";重启动作由用户手动做。
+- 热重载列必须有依据 (运行方式 → 有没有 HMR),不确定就问用户,不猜。
+- `go run .` 这类 **没有热重载**的写法要写进 rule,别让 AI 以为改了代码就自动生效。
+
+### 第四段起:项目补充条款
+
+用户针对这个项目给的其它纪律, **按顺序续写在后面**(第四段、第五段……),例如:
+
+- 文件写入位置 (禁止写哪些目录、跑测/调试产物必须落在哪儿)
+- 测试纪律 (用例归属、什么时候才允许新增 UT、端到端测试在哪台机器上跑)
+- 访问归属 (数据库 / 第三方接口只经哪个工具,不旁路直连)
+- dev 模式特有限制 (会真实计费的操作、凭据存储方式等)
+
+处理方式:用户给的条款 **逐条保留原意**、编号连续, **不合并不改写语义**。
+
+## 流程
+
+1. **收集事实 (不猜)**:
+    - `idea_get_run_configurations` → 真实存在的配置名 (第二段"run configuration"列只能来自这里)。
+    - `idea_search_file` 传 `q="*.run.xml"` + `paths: [".run"]` → 每个配置实际干什么 (命令 / 脚本 / npm script)。
+    - `package.json` / `pom.xml` / `go.mod` / `pyproject.toml` / `Cargo.toml` → 项目类型 → 决定第三段的热重载列。
+    - 端口:从 run configuration 的 option 或项目自身配置里读。
+2. **补齐缺口**:哪些应用进 standalone、哪些配置名对不上、端口与热重载不确定 —— 逐条向用户确认,不编。
+3. **写文件**:首次用 `idea_create_new_file` 写 `.opencode/rules/idea-standalone.md`;后续更新用 `idea_apply_patch`
+   **定向改**,不整文件重写。
+4. **校验**:第二段表格里每个配置名都能在 `idea_get_run_configurations` 里查到 —— **查不到就是错的**,不许用
+   "应该生效了"结案。
+
+## 铁律 (汇总)
+
+1. 四段结构不能缺:standalone 定义 → 应用与 run configuration → 热重载与重启提醒 → 用户补充条款。
+2. 第二段的启动方式 **只能是 IDEA run configuration**;不写手搓启动命令。
+3. AI 不启停本机进程 (含 `idea_execute_run_configuration`);判断需要重启时先取得用户明确授权。
+4. 配置名、端口、热重载三项都必须有依据;不确定就问用户。
+5. 用户补充条款保留原意、编号连续,不合并不改写。
+6. rule 只写项目级 `.opencode/rules/idea-standalone.md`,不写全局规则目录。

package/src/ide-guidance.js

@@ -61,15 +61,15 @@ export function buildIdeGuidance(projectPath) {
     `- \`idea_execute_run_configuration\`:跑已有配置;Shell Script 要 \`EXECUTE_IN_TERMINAL: false\`;覆盖参数(\`programArguments\` / \`workingDirectory\` / \`envs\`)需配置支持 \`supportsDynamicLaunchOverrides\`。`,
     ``,
     `### 终端`,
-    `- \`idea_execute_terminal_command\`:**项目内的一切命令执行都用它**,不要用原生 \`shell\`。`,
-    `  判据是"命令是否依赖项目的工具链 / 运行时 / 依赖环境",不是语言或工具名 —— Java、Python、Node、Go 之外,`,
-    `  Maven / Gradle、uv / pip / poetry、cargo、bundler、make / cmake、包管理器与构建、测试、代码生成等,全都算。`,
-    `  例外:纯操作系统级的通用命令(\`ls\` / \`cat\` / \`cp\` / \`mkdir\` / \`git\` 等)用原生 \`shell\` 即可。`,
-    `  记不清就不确定时:只要命令会调用项目的工具链,就用它,不要退回原生 \`shell\`。`,
-    `  - 必须 \`executeInShell: true\`:在用户真实 shell 里执行,**天然继承 IDE 里配好的运行时环境**(JDK / Node / Python / Go / Maven / uv 等及各版本管理器);原生 shell 可能用错版本。`,
+    `- 白名单制:命令用于本项目自身的构建 / 测试 / 运行,且首个可执行文件命中下表,才用 \`idea_execute_terminal_command\`;其余一律走原生 \`shell\`。`,
+    `- 白名单(按本项目类型取对应一行) ——`,
+    `  - Node / 前端(\`package.json\`):\`node\` / \`npm\` / \`npx\` / \`pnpm\` / \`yarn\` / \`vite\` / \`webpack\` / \`esbuild\` / \`tsc\` / \`jest\` / \`vitest\`。`,
+    `  - Java(\`pom.xml\` / \`build.gradle\`):\`java\` / \`javac\` / \`mvn\` / \`mvnw\` / \`gradle\` / \`gradlew\`。`,
+    `  - Python(\`pyproject.toml\` / \`requirements.txt\`):\`python\` / \`python3\` / \`pip\` / \`pip3\` / \`uv\` / \`poetry\` / \`pytest\`。`,
+    `  - Go(\`go.mod\`):\`go\` / \`gofmt\` / \`golangci-lint\`。`,
+    `  - \`executeInShell: true\`:在用户真实 shell 里执行,继承 IDE 配好的运行时环境;原生 shell 可能用错版本。`,
     `  - 按预期耗时传 \`timeout\`(毫秒),长任务给足;必要时传 \`maxLinesCount\` 控制返回行数。`,
-    `  - 连续命令传 \`reuseExistingTerminalWindow: true\`,复用同一个 IDE 终端窗口。`,
-    `  - 结果带 \`command_exit_code\` 与 \`command_output\`;\`cd\` 不跨调用保留,多步时在一条命令里用 \`&&\`。`,
+    `  - 连续命令传 \`reuseExistingTerminalWindow: true\`;结果带 \`command_exit_code\` 与 \`command_output\`,\`cd\` 不跨调用保留,多步用 \`&&\`。`,
     ``,
     `### 数据库 (数据源由用户在 IDE 里配置:不要自己建/改,不要向用户索取数据库凭据)`,
     `- \`idea_list_database_connections\`:先看有没有现成数据源;每条给 \`id\` / \`dbms\` / \`jdbcUrl\` / \`readOnly\` / \`isDDL\`。`,
@@ -103,6 +103,19 @@ export const MCP_RECOVERY_GUIDANCE_MARKED = [
   'This project is IDEA-connected and the plugin reconnects the IDE MCP automatically. When an idea_* call fails with a connection error (for example `MCP server "idea" is not available`), do not run extra probes or wait in tool calls: the reconnect is already under way, so retry the operation once. Only if it still fails, tell the user that IDEA MCP is unavailable and to run /open-in-idea.',
 ].join('\n');
 
+/**
+ * Recovery instruction for a marked project whose idea_* tools are NOT in this
+ * request's tool list. The connection dropped and the plugin is already
+ * reconnecting, but the reconnect only lands on a LATER request — so within this
+ * one a call can only fail with `No tool named "..." is currently available`.
+ * Saying "retry" here (as the MARKED variant does) is what makes the model fire
+ * exactly that doomed call.
+ */
+export const MCP_RECOVERY_GUIDANCE_RECONNECTING = [
+  '### IDEA MCP failure recovery',
+  'No idea_* tool is in this request: the IDE connection dropped and the plugin is reconnecting in the background. Do NOT call any idea_* tool now — it will fail with `No tool named "..." is currently available` — and do not fall back to shell/read/write for in-project work. Continue with what you can, or tell the user the IDE is reconnecting; if idea_* tools are still missing on a later message, ask the user to run /open-in-idea.',
+].join('\n');
+
 /**
  * Push the guidance onto a session `system` array. Called for every primary
  * model request, so it stays idempotent per request.
@@ -120,11 +133,17 @@ export function appendIdeGuidance(system, projectPath) {
 
 /**
  * @param {unknown} system
- * @param {{ marked?: boolean }} [options] `marked` picks the auto-reconnect variant
+ * @param {{ marked?: boolean, serving?: boolean }} [options] `marked` picks the
+ *   auto-reconnect variant; `serving: false` additionally picks the variant for
+ *   a request that has no idea_* tools at all, where a call can only fail.
  */
-export function appendIdeRecoveryGuidance(system, { marked = false } = {}) {
+export function appendIdeRecoveryGuidance(system, { marked = false, serving = true } = {}) {
   if (!Array.isArray(system)) return;
-  const text = marked ? MCP_RECOVERY_GUIDANCE_MARKED : MCP_RECOVERY_GUIDANCE;
+  const text = marked
+    ? serving
+      ? MCP_RECOVERY_GUIDANCE_MARKED
+      : MCP_RECOVERY_GUIDANCE_RECONNECTING
+    : MCP_RECOVERY_GUIDANCE;
   if (system.some((part) => part?.text === text)) return;
   system.push({ type: 'text', text });
 }

package/src/mcp/idea.js

@@ -146,7 +146,7 @@ export async function probePort(port, options = {}) {
         params: {
           protocolVersion: PROTOCOL_VERSION,
           capabilities: {},
-          clientInfo: { name: 'opencode-idea', version: '0.0.12' },
+          clientInfo: { name: 'opencode-idea', version: '0.0.14' },
         },
       }),
       signal: controller.signal,
@@ -217,7 +217,7 @@ export async function callTool(port, projectPath, name, args = {}, options = {})
       params: {
         protocolVersion: PROTOCOL_VERSION,
         capabilities: {},
-        clientInfo: { name: 'opencode-idea', version: '0.0.12' },
+        clientInfo: { name: 'opencode-idea', version: '0.0.14' },
       },
     });
     // The IDE's Streamable-HTTP endpoint binds follow-up requests to the session

package/src/plugin.js

@@ -78,13 +78,29 @@ const TOOL_REFRESH_POLL_MS = 25;
 const DEFAULT_EXECUTION_TIMEOUT_MS = 600000;
 // Background IDE liveness probe. The stdio bridge NEVER reports a dropped IDE
 // connection (it just hangs), so the plugin watches the IDE endpoint itself.
-// After HEARTBEAT_FAILURES consecutive misses it deactivates the `idea` server
-// — which kills the zombie bridge child AND removes the `idea_*` tools, so the
-// model can never call into a dead pipe — and latches a rebuild for the next
-// user message (the bridge never heals on its own).
+// ONE miss is already conclusive: a healthy localhost endpoint answers in
+// milliseconds, and a single probe already tolerates up to `mcpProbeTimeoutMs`
+// (1s). Requiring consecutive misses would only widen the window in which a
+// call already made against the zombie bridge keeps hanging. So on a miss the
+// plugin deactivates the `idea` server — killing the zombie bridge child AND
+// removing the `idea_*` tools, so the model can never call into a dead pipe —
+// and latches a rebuild for the next user message (the bridge never heals on
+// its own).
 const DEFAULT_HEARTBEAT_INTERVAL_MS = 5000;
-const DEFAULT_HEARTBEAT_FAILURES = 2;
-const IDEA_READY_TOOL_IDS = new Set(['idea_read_file', 'idea_apply_patch']);
+const DEFAULT_HEARTBEAT_FAILURES = 1;
+// Every IDE tool comes from the MCP server the plugin registers as `idea`, and
+// OpenCode namespaces a server's tools with its name — so `idea_*` IS the whole
+// set, the same predicate the request hooks use. "Ready" means at least one of
+// them is listed: OpenCode publishes an MCP catalog wholesale (one reload), so
+// one tool means the batch landed.
+//
+// This used to be a hard-coded pair (`idea_read_file` + `idea_apply_patch`),
+// which is not a property the plugin may assume: the IDE can rename a tool, and
+// the user can switch one off on the IDE's Exposed Tools page. Either one made
+// the wait unsatisfiable, so every `/open-in-idea` and every auto-rebuild burned
+// the full `toolRefreshTimeoutMs` and still reported `tools-loading` — telling
+// the user to re-run a command that could never succeed.
+const IDEA_TOOL_PREFIX = 'idea_';
 
 /**
  * IDEA MCP tools that must never reach the model.
@@ -459,8 +475,14 @@ export default {
     let heartbeatMisses = 0;
     // Latches when the IDE was seen down and the server was deactivated. It is
     // cleared ONLY by a successful rebuild — never by the endpoint coming back —
-    // because the bridge does not heal on its own.
+    // because the bridge does not heal on its own. It is set from TWO places:
+    // the heartbeat (the IDE port stopped answering) and the `context` hook (a
+    // request arrived without the `idea_*` tools).
     let needsRebuild = false;
+    // Set once a request in this session actually carried `idea_*` tools, so a
+    // later request without them is a DROP of this session's own connection —
+    // not a project that simply never connected.
+    let wasServing = false;
 
     // Project-level mark: has the user opted this project into IDEA via
     // `/open-in-idea`? One plugin instance serves one project (OpenCode
@@ -534,7 +556,7 @@ export default {
       while (Date.now() < deadline) {
         try {
           const ids = toolIds(await ctx.tool.list());
-          if ([...IDEA_READY_TOOL_IDS].every((id) => ids.includes(id))) return true;
+          if (ids.some((id) => id.startsWith(IDEA_TOOL_PREFIX))) return true;
         } catch {
           // The MCP catalog may still be settling; retry within the bounded wait.
         }
@@ -543,6 +565,27 @@ export default {
       return false;
     };
 
+    /**
+     * Does the local registry still list any of this server's tools?
+     *
+     * The IDE endpoint answering says nothing about the bridge OpenCode actually
+     * calls: when that child process dies, OpenCode drops every `idea_*` tool
+     * while the IDE keeps serving. The port probe reports "fine" and the model
+     * gets a tool list without the IDE — so this near end needs its own check,
+     * and it is a purely local read.
+     *
+     * Unavailable or failed reads report `true`: inventing a miss would tear down
+     * a working bridge, which is worse than skipping one tick.
+     */
+    const ideaToolsPresent = async () => {
+      if (typeof ctx.tool?.list !== 'function') return true;
+      try {
+        return toolIds(await ctx.tool.list()).some((id) => id.startsWith(IDEA_TOOL_PREFIX));
+      } catch {
+        return true;
+      }
+    };
+
     const refreshIdeTools = async () => {
       if (typeof ctx.mcp.reload === 'function') await ctx.mcp.reload();
       // Reconcile the MCP servers above, then replay the tool registry so the
@@ -593,13 +636,20 @@ export default {
     // Serialize reconciles so overlapping callers can never register/activate
     // the IDE concurrently (which would leak registrations).
     let reconcileChain = Promise.resolve();
+    // Non-zero while a reconcile is queued or running. A rebuild tears the
+    // registration down before it registers again, so the tools are briefly
+    // absent on purpose — the heartbeat must not read that as a loss.
+    let reconcileBusy = 0;
     const enqueue = (task) => {
+      reconcileBusy += 1;
       const next = reconcileChain.then(task);
       reconcileChain = next.then(
         () => {},
         () => {},
       );
-      return next;
+      return next.finally(() => {
+        reconcileBusy -= 1;
+      });
     };
     const reconcile = (options) => enqueue(() => reconcileOnce(options));
 
@@ -744,6 +794,49 @@ export default {
         : result;
     };
 
+    /**
+     * Coalesced background reconnect.
+     *
+     * The `context` hook latches the rebuild the moment a request shows the tools
+     * are gone, but a latch alone only fires on the NEXT user message — one whole
+     * turn later, which is exactly the gap that made a dead session sit there
+     * until `/open-in-idea` was run by hand. This runs out of band (it never
+     * blocks the request) so the next request — the following agent-loop step, or
+     * any later message — already carries the tools again.
+     *
+     * @returns {Promise<void>}
+     */
+    /** @type {Promise<void> | undefined} */
+    let reviveInFlight;
+    const reviveIde = () => {
+      // The mark gates EVERY reconnect, not just the ones started from a user
+      // message: a background attempt must never resurrect the IDE for a project
+      // the user closed with `/close-in-idea`.
+      if (disposed || markCache !== true) return Promise.resolve();
+      if (reviveInFlight) return reviveInFlight;
+      const run = (async () => {
+        try {
+          const result = await runOpenInIdea();
+          // `/close-in-idea` can land while this was in flight; it wins.
+          if (markCache !== true) {
+            await deactivateIde();
+            return;
+          }
+          if (result.port !== undefined) {
+            needsRebuild = false;
+            heartbeatMisses = 0;
+          }
+        } catch {
+          // best effort: the latch stays set, and the prompt hook retries
+        }
+      })();
+      reviveInFlight = run;
+      void run.then(() => {
+        if (reviveInFlight === run) reviveInFlight = undefined;
+      });
+      return run;
+    };
+
     // Setup never probes or connects the IDE — everything is on `/open-in-idea`.
     await reconcile({ probeIde: false });
 
@@ -764,21 +857,29 @@ export default {
       heartbeatBusy = true;
       try {
         const port = await findIdePort(ports, { timeoutMs: mcpProbeTimeoutMs }).catch(() => undefined);
-        if (port !== undefined) {
+        // Two independent failures to catch. The endpoint can stop answering (the
+        // IDE is gone), or it can keep answering while the bridge OpenCode calls
+        // has died — the second one is invisible to the probe AND to the model,
+        // which is why the local registry gets checked too.
+        if (port !== undefined && (reconcileBusy > 0 || (await ideaToolsPresent()))) {
           heartbeatMisses = 0;
           return;
         }
         heartbeatMisses += 1;
         if (heartbeatMisses < heartbeatFailures) return;
-        // The IDE is gone. Deactivating kills the zombie bridge child and
-        // removes the `idea_*` tools, so the model cannot call into a dead
-        // pipe. Latch a rebuild for the next user message.
+        // Either end is down. Deactivating kills the zombie bridge child and
+        // removes the `idea_*` tools, so the model cannot call into a dead pipe.
         const kicked = await enqueue(async () => {
           if (disposed || registrations.length === 0) return false;
           await deactivateIde();
           return true;
         });
         if (kicked) needsRebuild = true;
+        // The IDE is still reachable, so reconnecting needs no launch — reconnect
+        // now instead of leaving the session tool-less until the next message. A
+        // dead endpoint still waits for one: that path may `open -a`, and the
+        // heartbeat must never start the IDE on its own.
+        if (needsRebuild && port !== undefined) await reviveIde();
       } finally {
         heartbeatBusy = false;
       }
@@ -903,8 +1004,32 @@ export default {
       sessionRegistration = await ctx.session.hook('context', (event) => {
         const tools = event?.tools;
         const serving = tools !== undefined && Object.keys(tools).some((name) => name.startsWith('idea_'));
-        if (serving) removeIdeaToolDefinitions(tools, HIDDEN_IDEA_TOOLS);
-        if (markCache === true || serving) appendIdeRecoveryGuidance(event?.system, { marked: markCache === true });
+        if (serving) {
+          wasServing = true;
+          removeIdeaToolDefinitions(tools, HIDDEN_IDEA_TOOLS);
+        } else if (wasServing && tools !== undefined && markCache === true) {
+          // This session HAD the tools and this request does not. The heartbeat
+          // alone cannot catch every way that happens: a bridge child can die
+          // while the IDE port keeps answering, and a failed reconnect tears the
+          // registration down WITHOUT latching anything (`reconcileOnce` tears
+          // down first and then finds no port, so `kicked` never runs). Without
+          // a latch the `prompt` hook has nothing to fire on, so the next
+          // message would send the model a tool list without `idea_*` and
+          // recover nothing. Latch it here instead, where "is the IDE serving
+          // THIS request?" is a fact. `wasServing` keeps this from firing for a
+          // project that never connected in this session — setup deliberately
+          // does not connect on its own.
+          needsRebuild = true;
+          wasServing = false;
+          // Do not wait for the next user message. The latch is read by the
+          // `prompt` hook, which has ALREADY run for this request — so without
+          // this the session would stay tool-less for the rest of the turn and
+          // need one more message before anything happened.
+          void reviveIde();
+        }
+        if (markCache === true || serving) {
+          appendIdeRecoveryGuidance(event?.system, { marked: markCache === true, serving });
+        }
         if (!injectGuidance) return;
         // Guidance promises tools the model can call, so it only goes out when
         // they are actually in this request.
@@ -912,10 +1037,12 @@ export default {
         appendIdeGuidance(event?.system, projectPath);
       });
 
-      // Rebuild after a heartbeat-detected drop. It reads only the in-memory
-      // `needsRebuild` latch, so it is a cheap no-op on every other message.
-      // OpenCode awaits `prompt` before the request is built, so when the IDE is
-      // back, the message that triggers this already carries working tools.
+      // Rebuild after a detected drop — the heartbeat (dead port) or the context
+      // hook above (tools gone from a request) latches `needsRebuild`. Reading
+      // only that in-memory latch keeps this a cheap no-op on every other
+      // message. OpenCode awaits `prompt` before the request is built, so when
+      // the IDE is back, the message that triggers this already carries working
+      // tools.
       promptRegistration = await ctx.session.hook('prompt', async (event) => {
         if (disposed || !needsRebuild || markCache !== true) return;
         // Never react to the plugin's own notices, or recovery would feed on
@@ -925,11 +1052,15 @@ export default {
         // — verified live, and it made this rebuild never run.
         const text = event?.prompt?.text;
         if (typeof text === 'string' && text.startsWith(NOTICE_PREFIX)) return;
-        const result = await runOpenInIdea();
-        if (result.port !== undefined) {
-          needsRebuild = false;
-          heartbeatMisses = 0;
-        }
+        // Awaited on purpose: the message that triggers this already carries
+        // working tools. A background attempt already in flight is joined — but
+        // joining is not trying: if that attempt had already failed, this message
+        // would be swallowed and would carry no tools, which is exactly the bug
+        // this hook exists to prevent. So when we joined one and the latch is
+        // still set, this message gets an attempt of its own.
+        const joined = reviveInFlight !== undefined;
+        await reviveIde();
+        if (joined && needsRebuild) await reviveIde();
       });
 
       // The only self-initiated action: when an `idea_*` call fails in a way