@zoisythe/codex-codeintel 0.0.0-stage → 0.10.0

package/docs/examples/lsp-client.automatic-off.json

@@ -0,0 +1,4 @@
+{
+	"schemaVersion": 1,
+	"automaticDiagnostics": { "postToolUse": "off", "stop": "off" }
+}

package/docs/examples/lsp-client.custom-server.json

@@ -0,0 +1,13 @@
+{
+	"schemaVersion": 1,
+	"lsp": {
+		"python": {
+			"command": ["/absolute/path/to/.venv/bin/ty", "server"],
+			"extensions": [".py", ".pyi"],
+			"env": {},
+			"initialization": {}
+		},
+		"typescript": "tsc",
+		"rust": false
+	}
+}

package/docs/examples/lsp-client.default.json

@@ -0,0 +1,9 @@
+{
+	"schemaVersion": 1,
+	"projectChecks": "auto",
+	"automaticDiagnostics": { "postToolUse": "delta", "stop": "errors" },
+	"lsp": { "python": "ty", "typescript": "typescript", "cpp": "clangd", "rust": "rust" },
+	"lint": { "javascript": "auto", "python": "auto" },
+	"formatting": { "tabSize": 4, "insertSpaces": true },
+	"exclude": []
+}

package/docs/examples/lsp-client.project-checks.json

@@ -0,0 +1,33 @@
+{
+	"schemaVersion": 1,
+	"projectChecks": [
+		{
+			"name": "web-types",
+			"cwd": "web",
+			"command": ["node_modules/.bin/tsc", "--noEmit", "--pretty", "false"],
+			"parser": "tsc",
+			"coverage": ["src/**/*.ts", "src/**/*.tsx"]
+		},
+		{
+			"name": "web-lint",
+			"cwd": "web",
+			"command": ["node_modules/.bin/eslint", "src", "--format", "json"],
+			"parser": "eslint",
+			"coverage": ["src/**/*.ts", "src/**/*.tsx"]
+		},
+		{
+			"name": "api-types",
+			"cwd": "api",
+			"command": [".venv/bin/ty", "check", "--output-format", "concise", "--color", "never"],
+			"parser": "ty",
+			"coverage": ["src/**/*.py", "src/**/*.pyi"]
+		},
+		{
+			"name": "api-lint",
+			"cwd": "api",
+			"command": [".venv/bin/ruff", "check", "--no-fix", "--no-fix-only", "--output-format", "json", "src"],
+			"parser": "ruff",
+			"coverage": ["src/**/*.py", "src/**/*.pyi"]
+		}
+	]
+}

package/docs/examples/lsp-client.stop-gate.global.json

@@ -0,0 +1,5 @@
+{
+	"schemaVersion": 1,
+	"automaticDiagnostics": { "stop": "errors" },
+	"stopGate": "introduced-errors"
+}

package/docs/testing/hooks-host.md

@@ -0,0 +1,13 @@
+# Codex 原生 Hook 宿主验收
+
+该步骤需要支持 async command Hook、SubagentStop.agent_id 和 Interrupt 的当前 Codex 宿主。先构建交付 bundle、审阅 hooks/hooks.json，再由用户通过 /hooks 重新审阅；在新会话运行。不要复制、修改信任记录或使用绕过 Hook 信任的参数。保留原有自动诊断/门禁选择；需要启用测试模式时只使用用户已经授权的隔离测试配置。
+
+记录宿主版本、插件 bundle SHA-256、六个已审阅事件、测试工作区和运行时间；不要保存凭据或未经筛选的用户 transcript。
+
+1. 在隔离 TypeScript 或 Biome fixture 使用 Bash 读取文件，确认没有启动检查；分别通过 Bash 写入、apply_patch 和 mcp__lsp__apply 修改源码，核对宿主实际投递的规范工具名与 tool_use_id。八个只读 MCP 工具不能触发写分析，rename/format/actions 只预览。
+2. 使用缓慢检查器让 PostToolUse 持续运行，确认原工具结果立即可用，后台结果经宿主原生 async 投递。普通 Stop 应在 1.5 秒内结束，等待后台结果不超过 300 ms，pending 留存；注意宿主只在安全点追加异步上下文，不自动创建新 turn。
+3. 由用户明确授权两个测试子代理，各修改不同文件并并行结束，主任务同时 Stop。核对显式 agent_id 的独立反馈和 shared 标记，子代理不得收到其他代理交付或 decision:block。仅主任务在已启用的全局门禁下，可对当前可靠新增错误每 turn 请求一次续跑。
+4. 正在等待后台结果时使用宿主中断操作，捕获真实 Interrupt 事件。确认中断迅速完成，明确归属的旧等待被解除，其他代理仍可领取结果；共享 LSP 和进行中的 MCP 写入未被中断。结束会话后迟到结果不得重新出现。
+5. 触发 resume、clear、fork 和 compact；前三者按会话语义复用或重建，compact 不重新发现基线。每条反馈最多 2 KiB、五条关键诊断；缓存 diagnostics 可查看详情。核对 stdout 成功写出才 ACK，重试允许使用相同 deliveryId。
+
+仓库中的 hook-flow、automatic-e2e、background-hooks-e2e 测试验证实际服务/CLI、竞态、输出预算、ACK 和取消；它们直接输入 Hook JSON，不证明宿主 matcher、原生 async 调度或真实 agent_id/Interrupt 投递正确。未完成上述宿主步骤时必须在验收记录中明确标为待验收。Linux/macOS/Windows CI 验证 bundle 行为，不需要本机 Rust。

package/docs/usage.md

@@ -0,0 +1,226 @@
+# Codex CodeIntel 使用指南
+
+本文对应 **0.10.0**。插件提供九个 MCP 工具，Hooks 与 MCP 共享本地 LSP、项目检查和诊断缓存。运行要求 Node.js >=22.12.0；交付 bundle 不需要安装运行时依赖。
+
+## 安装与首次使用
+
+```sh
+codex plugin marketplace add https://github.com/zoisythe/codex-codeintel
+codex plugin add codex-codeintel@codex-codeintel
+```
+
+开启新会话并通过 `/hooks` 检查 Hook 定义。使用 setupLSP（`$setup-lsp`）配置、安装或修复所需工具。普通编码中能力缺失只需报告一次并继续其他工作。
+
+<a id="configuration"></a>
+## 配置位置与覆盖规则
+
+读取 `$CODEX_HOME/lsp-client.json`（默认 `~/.codex/lsp-client.json`）和项目的 `.codex/lsp-client.json`。优先级为内置、全局、项目；两者都使用 `schemaVersion:1`。同一语言的 LSP 对象整体替换；exclude/projectChecks 数组整体替换。
+
+```json
+{
+  "schemaVersion":1,
+  "projectChecks":"auto",
+  "lsp":{"python":"ty","typescript":"typescript","go":"gopls","cpp":"clangd","rust":"rust"},
+  "lint":{"javascript":"auto","python":"auto"},
+  "automaticDiagnostics":{"postToolUse":"off","stop":"off"}
+}
+```
+
+| 字段 | 含义 |
+| --- | --- |
+| lsp | 语言到内置名称、false 或自定义 command/extensions/env/initialization 对象的映射 |
+| lint.javascript | auto、biome、eslint、off |
+| lint.python | auto、ruff、off |
+| formatting | tabSize（1–16）、insertSpaces |
+| exclude | 相对路径正向 glob；不接受绝对路径、反斜线、否定或 .. |
+| projectChecks | auto 或显式检查数组；数组替换自动发现结果 |
+| automaticDiagnostics | postToolUse=delta/off，stop=errors/off；默认均 off |
+| stopGate | 只有用户全局配置可设 introduced-errors；默认 off |
+
+本地工具优先，显式命令失败不回退到下载版本。Python ty 与 Ruff 独立；lint=off 不会禁用显式格式化。TypeScript 默认使用传统 language server，原生 TypeScript 7 可选择 tsc。Go 使用 gopls；C/C++ 和 Rust 使用现有本地工具链。
+
+配置损坏不阻断编辑。status、缓存读取仍可用；可定位的语言/检查配置错误只影响相关能力。status 不启动 LSP、不下载工具，unverified 不代表已经成功启动。目录信任记录不控制插件执行。
+
+## 九个 MCP 工具
+
+所有调用使用绝对 workspace。位置为 **1-based、UTF-16 列**。位置操作接受以下一种定位方式：
+
+- line/column；
+- symbol，例如 Class.method；重载索引由 symbols 结果提供；
+- pattern，例如 function @@greet，以 @@ 标记光标。
+
+重名或多个锚点匹配返回候选，插件不会猜测。工作区符号搜索仍使用 navigate 的 operation=symbols 和 query；path 用于选择语言服务器。
+
+| 工具 | 用途 |
+| --- | --- |
+| check | 项目 CLI 检查；active 启动任务，cached 读取 job，跟随 next |
+| diagnostics | 显式路径、turn/session 的 LSP、lint 或 both 检查；active/cached |
+| status | 工具、配置、能力、失败和任务状态；refresh 重新验证 |
+| navigate | 原子语义查询及 outline |
+| rename | 只读重命名计划 |
+| format | 只读格式化计划 |
+| inspect | symbol 组合探索或 impact 影响分析 |
+| actions | list/explain/preview 修复动作 |
+| apply | 消费既有计划并顺序写入；唯一源码写入口 |
+
+### 项目检查与诊断
+
+```json
+{"workspace":"/project","run":"active"}
+```
+
+使用 check。任务未完成时跟随返回的 next；state=running/failed/stale 不能证明项目无错误。CLI 也可使用 `codex-codeintel check <workspace>`。
+
+diagnostics 示例：
+
+```json
+{"workspace":"/project","paths":["src/main.ts"],"source":"both","run":"active","severity":"error"}
+```
+
+scope 可为 paths、turn、session；多会话时必须提供 session。路径诊断不能用省略路径或 "." 代替全项目检查，应使用 check。rule/severity 只筛选展示，不改变实际检查、基线或缓存；失败和 pending 状态不会被过滤隐藏。
+
+默认诊断保留位置、规则、严重性、消息和已知修复可用性。修复编辑、完整文档及工具原始信息不会随每次诊断发送。统计按规则/文件汇总；归因仅使用可靠的既有 checker 基线，缺失时为 unattributed。不同规则、检查器与覆盖范围不能相互替代基线。
+
+projectChecks 的每项包含 name、cwd、command、parser、coverage；相对命令/coverage 均相对 cwd。支持 parser：tsc、ty、go、cargo、ruff、eslint、biome、sarif、json。自定义 json 为：
+
+```json
+{"diagnostics":[{"path":"src/a.ts","line":1,"column":1,"severity":"error","source":"rule","message":"problem"}]}
+```
+
+自动发现支持根 tsconfig、ty、Go module、Cargo workspace 和匹配的 lint 配置。TypeScript references/多包、特殊 features、自定义语言及 C/C++ CLI 检查应显式配置。命令必须只检查，不修改源码、自动修复或安装依赖。示例见 [docs/examples](examples/)。
+
+Go 自动检查使用 go vet -mod=readonly -json ./...，由 go list 确认实际 Go/Test 输入，不把 build tags、平台排除或其他 module 的文件算作覆盖。自动检查禁止 Go 工具链/模块下载；需要的环境和依赖应先准备好。缺失工具或包发现失败为 unavailable/failed，不能返回干净结果。
+
+### 导航与组合分析
+
+navigate 支持 definition、declaration、references、symbols、prepare_rename、hover、typeDefinition、implementation、signatureHelp、incoming、outgoing、supertypes、subtypes、completion。
+
+```json
+{"workspace":"/project","path":"src/main.ts","operation":"symbols"}
+```
+
+outline 默认只展示顶层；传入 symbol 展开该节点的直接成员。成员过多会分页，不再因一个大 class 超限而返回空列表。关系查询返回直接关系；进一步展开需重新定位对应符号。服务器不支持时明确返回 unsupported。
+
+```json
+{"workspace":"/project","path":"src/main.ts","operation":"symbol","symbol":"greet","source":true}
+```
+
+使用 inspect 聚合签名/文档、定义、引用摘要和调用关系；source 默认省略。operation=impact 接收明确 path/paths 或定位符，汇总顶层类型/函数及类型成员的引用，排除局部变量、字段噪声。symbols 可指定文件内的符号路径集合，逐项保留歧义或失败；调用方来自调用层级，普通引用单独统计。transitive=true 最多追加一层，预算不足明确 partial。各子查询独立报告失败。
+
+候选测试仅依据文件命名和符号引用，不是运行时覆盖证明。零引用不证明可安全删除；没有并发安全或死代码自动裁决。
+
+### lint 与 LSP 修复
+
+```json
+{"workspace":"/project","path":"src/main.py","operation":"list","source":"lint"}
+```
+
+使用 actions。source=lint/lsp/both，默认 both。list 返回动作 id、标题、来源、适用性和不可用原因，不默认返回全部编辑。
+
+explain 接收 path 和 rule。返回当前安装工具可确认的规则说明、文档和有效设置；details=true 按需展开。工具未提供配置来源或忽略原因时明确为 unknown，不猜测。
+
+preview 传入选定 ids，或在明确文件范围内批量生成计划：
+
+```json
+{"workspace":"/project","operation":"preview","ids":["action-id"]}
+```
+
+批量默认只选择工具明确标记 safe 的动作。unsafe、unknown 和 suggestions 需显式选择；ESLint fixable 不会被重标成 safe。Ruff/ESLint 保留逐诊断编辑，Biome 通过 stdin 生成文件级修复；按 rule 预览时仅处理当前诊断已确认启用的规则，不通过筛选开启原本关闭的规则。
+
+LSP 动作可 resolve 后生成纯文本计划。带 command、disabled 或创建/删除/移动文件的动作标为 unsupported，不执行其命令，也不部分应用。lint 修复不会顺带调用 formatter、添加抑制注释或修改配置。
+
+### 编辑计划与 apply
+
+rename 示例：
+
+```json
+{"workspace":"/project","path":"src/main.ts","symbol":"greet","newName":"welcome"}
+```
+
+format 示例：
+
+```json
+{"workspace":"/project","paths":["src/main.ts"]}
+```
+
+两者都只生成 plan、文件摘要和 diff，不写入。随后：
+
+```json
+{"workspace":"/project","plan":"returned-plan-id"}
+```
+
+调用 apply。对已授权修改可连续执行预览与应用，无需新增人工批准步骤。计划只描述文本修改；它不包含内存类型模拟，也不保证构建或测试成功。
+
+计划存在工作区服务的有界内存中，服务重启即失效。源文件、配置、工具或请求环境变化会使计划失效。应用先预检所有目标，冲突、越界、符号链接变化或重叠编辑会拒绝；之后逐文件确认并写入。
+
+计划进入应用后被消费，不能重放。取消/失败返回实际修改路径；多文件操作不承诺原子回滚。写后诊断失败是补充状态，不能因此再次应用同一个计划。需要继续操作时重新生成计划。
+
+## 分页与返回信息
+
+默认最多 20 项，详情页约 8 KiB，结构化输出也受预算控制。文本仅作短摘要。始终跟随 next 提供的完整参数；不要自行计算 offset、复制旧 revision 或拼接游标。
+
+大型嵌套值拆成 items 中的字段片段：field 使用 result["key"][index] 表示原输出路径；value 保存完整小值，part/text 保存按序文本分段。路径中带点或斜线的键使用带引号的下标，避免歧义。源码、diff 和大 outline 可以完整续取，不静默丢失。底层项目任务或诊断批次仍需继续时，最后一页的 next 转交对应任务的后续参数。
+
+查询游标绑定查询、快照、配置及工具；apply 的后续页绑定已发生的执行记录，因此后续源码修改不妨碍读完 modifiedPaths。失效时重新发起原查询；不要用不同的过滤条件复用旧游标。页面中的 partial/failed/pending 信息必须保留，分页完成不代表底层分析已完成。
+
+## 自动 Hook 反馈
+
+自动反馈默认关闭，保留现有 automaticDiagnostics 和全局 stopGate 选择，不增加配置项。需要支持原生异步 command Hook 和 Interrupt 的当前 Codex 宿主；没有旧宿主兼容执行模式。Hooks 不调用 apply，不自动修复或格式化源码。
+
+| 事件 | 处理方式 |
+|---|---|
+| SessionStart | 同步入口预算 500 ms，保存修改前快照并登记基线任务，不等待项目检查。仅 startup/resume/clear/fork；compact 不重复发现。resume 复用有效状态，其余建立新 epoch。 |
+| PostToolUse | 原生 async，仅匹配 Bash、apply_patch、mcp__lsp__apply。内部总预算 310 秒，宿主 timeout 330 秒；原工具结果不受影响。已知只读 shell 只领取完成的反馈，不启动服务或检查。 |
+| Stop | 普通反馈总预算 1.5 秒，最多等待结果 300 ms；变化发现和检查可在后台继续。显式全局门禁开启时保留 44 秒总预算。 |
+| SubagentStop | 独立代理反馈，总预算 1.5 秒，始终不能请求续跑。 |
+| SessionEnd | 内部预算 1.6 秒、宿主 3 秒，取消任务并以 epoch 失效旧交付。 |
+| Interrupt | 内部预算 1 秒、宿主 3 秒，解除等待、取消明确属于被中断轮次的自动任务；身份不明保留 pending，不终止共享 LSP 或 MCP 写入。 |
+
+只有明确 agent_id 的事件属于子代理，不从 transcript 猜测。工作区版本、LSP 和缓存共享，代理任务等待、轮次、反馈记录分别保存；归属不明的结果标记 shared，由主任务 Stop 汇总。MCP 的 session 仍表示共享会话。SubagentStop 不消费主任务或其他代理的反馈。
+
+只有主任务 Stop 在用户全局 stopGate=introduced-errors 时，才可为可靠、覆盖且新鲜的新增错误请求每 turn 最多一次修复。缺少修改前基线、未知、失败、pending、stale 不阻断。setupLSP 不自动启用门禁。SessionStart 的 additionalContext 可供模型读取；Stop/SubagentStop 普通输出是 UI 摘要，不能据此声称模型已经读取。
+
+写事件按 session epoch、明确代理及 tool_use_id 幂等登记；没有 ID 时不猜测重复。合并窗口 200 ms，连续变化最长延后 1 秒，以当前内容哈希确认快照。apply 的完整 modifiedPaths（含部分写入）用于范围提示；分页、未知或不完整结果回退文件变化发现。分析身份和快照相同时复用 apply 写后的诊断。
+
+每条自动反馈最多 2 KiB UTF-8、五条关键诊断，报告 introduced/resolved/unattributed/pending 数量；同一状态去重，每代理每 turn 总量最多 8 KiB，并为收尾摘要预留空间。详情使用现有 diagnostics(run=cached, scope=session) 并提供共享 session。内部 hook_wait 仅长轮询已登记任务，单次最多 20 秒，不新增 MCP 工具。
+
+deliveryId、sourceTurn 和内容快照随交付保留，发送前复核新鲜度。ACK 仅表示 stdout 成功写出，ACK 失败可使用同一 ID 重发；不保证模型层恰好一次接收。没有证明建立于修改前的检查始终未归因。
+
+本版升级内部元数据格式，不迁移旧交付记录。更新后通过 /hooks 重新审阅定义，并在新会话使用；插件不修改信任记录或用户配置。真实宿主验收按 [Hooks 验收步骤](testing/hooks-host.md) 执行，CLI JSON 测试不能替代宿主原生异步、路由和 Interrupt 检查。
+
+## 排查问题
+
+用 status 配合代表性 path 查看工具选择与能力；修复后 refresh=true。现有命令启动失败不选择下载替代品。Windows 的 Path/PATH 在请求环境中统一规范化；显式空 PATH 仍然有效。
+
+依赖安装、构建/链接与测试仍需项目自己的命令。check 完成只代表指定检查完成。
+
+### 独立 Rust CI
+
+`.github/workflows/rust.yml` 独立运行于 Linux 和 Windows，固定 Rust 1.99.1 及配套的 rust-analyzer、rust-src、rustfmt。工具只安装到 CI runner，本机日常开发和默认 `npm test` 不要求 Rust。
+
+`npm run test:rust` 是需要已准备工具链的真实验收入口；缺少工具会失败，不会跳过。用例通过已交付 bundle 验证诊断及修复后的更新、符号/锚点定位、引用和调用、组合探索与候选测试关联、重命名/格式化/Code Action 的预览与 apply，以及 Cargo 工作区检查。fixture 只依赖本地 path crate，预先生成 lockfile，检查期间禁用依赖下载。
+
+CI 保留工具版本、测试日志及 MCP/fixture 记录为 `rust-<os>` artifact，保留 14 天。日志成功上传不代表验收通过，应以对应 job 的结果为准。新入口与历史多语言 `test:real` 的 Rust 开关独立。
+
+<a id="limits"></a>
+## 范围限制与本地数据
+
+发现预算 10,000 文件，单文件读取预算 1 MiB，paths 最多 200 项。影响分析每次最多处理 200 个符号、追加一层时最多 100 个间接节点；超限明确 partial。组合查询和编辑计划需要完整的工作区快照；超出发现或单文件预算时明确拒绝，需缩小 workspace 或配置 exclude。项目检查预算五分钟。
+
+无遥测。源码、诊断基线和未解决问题留在私有本地缓存。计划与动作在服务内存中，工作区服务空闲约五分钟退出。不同用户、workspace、CODEX_HOME 和 bundle 隔离；停止服务后可清理 CODEX_LSP_CACHE。
+
+<a id="upgrade"></a>
+## 从 0.9 升级
+
+| 移除的旧名 | 新名 |
+| --- | --- |
+| check_project | check |
+| check_diagnostics / lsp_diagnostics | diagnostics |
+| lsp_status | status |
+| lsp_navigation | navigate |
+| lsp_rename | rename → apply |
+| lsp_format | format → apply |
+
+旧名只返回迁移提示，不执行，也不保留隐藏调用别名。更新提示词、Skills 和调用脚本，并启动新会话。
+
+rename/format 的含义发生变化：它们是只读计划工具；apply 是唯一源码写入口。配置仍使用 schemaVersion:1，不需要重新创建全局配置。保留既有 automatic-off 和全局门禁选择；重新审阅 Hook 定义。

package/hooks/hooks.json

@@ -0,0 +1,63 @@
+{
+	"hooks": {
+		"SessionStart": [
+			{
+				"matcher": "^(startup|resume|clear|fork)$",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook",
+						"timeout": 3
+					}
+				]
+			}
+		],
+		"SessionEnd": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook",
+						"timeout": 3
+					}
+				]
+			}
+		],
+		"PostToolUse": [
+			{
+				"matcher": "^(Bash|apply_patch|mcp__lsp__apply)$",
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook",
+						"async": true,
+						"timeout": 330
+					}
+				]
+			}
+		],
+		"Stop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook",
+						"timeout": 50
+					}
+				]
+			}
+		],
+		"SubagentStop": [
+			{
+				"hooks": [
+					{
+						"type": "command",
+						"command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook",
+						"timeout": 3
+					}
+				]
+			}
+		],
+		"Interrupt": [{ "hooks": [{ "type": "command", "command": "node \"${PLUGIN_ROOT}/dist/cli.js\" hook", "timeout": 3 }] }]
+	}
+}

package/package.json

@@ -1,6 +1,70 @@
 {
-  "name": "@zoisythe/codex-codeintel",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@zoisythe/codex-codeintel",
+	"version": "0.10.0",
+	"description": "Codex code intelligence with LSP/lint diagnostics, symbol navigation, rename, formatting, and automatic Hooks.",
+	"type": "module",
+	"packageManager": "npm@11.12.1",
+	"license": "MIT",
+	"homepage": "https://github.com/zoisythe/codex-codeintel",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/zoisythe/codex-codeintel.git"
+	},
+	"bugs": {
+		"url": "https://github.com/zoisythe/codex-codeintel/issues"
+	},
+	"keywords": [
+		"codex",
+		"codex-plugin",
+		"lsp",
+		"language-server-protocol",
+		"mcp",
+		"diagnostics"
+	],
+	"bin": {
+		"codex-codeintel": "./dist/cli.js"
+	},
+	"files": [
+		"dist",
+		"hooks",
+		"skills",
+		".codex-plugin",
+		".mcp.json",
+		"LICENSE",
+		"NOTICE",
+		"README.md",
+		"CHANGELOG.md",
+		"docs/usage.md",
+		"docs/testing/hooks-host.md",
+		"docs/examples/*.json"
+	],
+	"scripts": {
+		"build": "node scripts/build.mjs",
+		"test": "node ./node_modules/vitest/vitest.mjs --run && npm run test:install && npm run test:typescript && npm run test:features",
+		"test:watch": "node ./node_modules/vitest/vitest.mjs",
+		"typecheck": "node ./node_modules/typescript/bin/tsc --noEmit",
+		"lint": "node ./node_modules/@biomejs/biome/bin/biome check src test scripts",
+		"lint:fix": "node ./node_modules/@biomejs/biome/bin/biome check --write src test scripts",
+		"check": "node ./node_modules/typescript/bin/tsc --noEmit && node ./node_modules/@biomejs/biome/bin/biome check src test scripts && node scripts/build.mjs",
+		"test:install": "node --test test/install-smoke.test.mjs test/runtime-e2e.test.mjs test/resolution-e2e.test.mjs test/diagnostic-e2e.test.mjs test/trust-e2e.test.mjs test/automatic-e2e.test.mjs test/background-hooks-e2e.test.mjs",
+		"test:typescript": "node --test test/typescript-native-e2e.test.mjs",
+		"test:real": "node --test test/three-language-e2e.test.mjs test/temporary-e2e.test.mjs test/automatic-real-e2e.test.mjs test/setup-profile-e2e.test.mjs",
+		"test:features": "node scripts/prepare-features.mjs && node --test test/features-e2e.test.mjs",
+		"test:rust": "node --test test/rust-e2e.test.mjs"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.12",
+		"@types/node": "^22.12.0",
+		"esbuild": "0.28.2",
+		"eslint": "9.39.4",
+		"smol-toml": "1.7.0",
+		"typescript": "7.0.2",
+		"typescript-language-server": "5.1.3",
+		"vite": "^8.2.2",
+		"vitest": "^5.0.0"
+	},
+	"engines": {
+		"node": ">=22.12.0"
+	},
+	"author": "zoisythe"
+}

package/skills/code-intelligence/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: code-intelligence
+description: Use CodeIntel checks, compact navigation/context and previewed lint/LSP edits; handle optional automatic feedback.
+---
+
+Use the absolute user repository as workspace. Positions are 1-based UTF-16 columns; choose line/column, symbol path or a unique @@ pattern.
+
+Use check for project CLI checks; diagnostics for explicit paths or turn/session, source=lsp/lint/both and active/cached. Filters affect display only. Follow returned next arguments through every page; partial, stale, failed and pending do not mean clean.
+
+Use status for configuration, local tools, capabilities and failures without starting servers. Refresh after repairs. For installation/configuration requests use [setupLSP](../setup-lsp/SKILL.md) ($setup-lsp); during ordinary coding report missing capabilities once and continue.
+
+Use navigate for atomic queries. symbols shows a top-level outline; symbol expands a node, query searches the workspace. Use inspect operation=symbol for a compact overview, source=true only when source is needed; operation=impact finds callers and candidate tests. Test association is not runtime coverage, and zero references is not proof of safe deletion.
+
+Use actions operation=list/explain/preview for lint/LSP fixes. Batch preview selects only vendor-safe actions; select ids explicitly for unsafe/unknown/suggestions. Command/resource actions are unsupported. Never infer safety from fixable alone.
+
+rename and format only produce a plan and diff. apply is the only source writer. After an authorized edit, preview then apply without adding a manual approval step. Keep applies sequential; plans are consumed and cannot be replayed. On cancellation/failure, read every modifiedPaths page before doing anything else. Follow-up diagnostic failure does not undo writes.
+
+All nine tools are check, diagnostics, status, navigate, rename, format, inspect, actions, apply. Old underscore names are removed.
+
+Automatic feedback defaults off and requires a current Codex host with native async Hooks and Interrupt. PostToolUse feedback is informational; its asynchronous process does not replace the tool result. Subagents receive independent feedback and never request continuation. Only the main Stop may use the explicit global gate for one repair pass per turn, with confirmed fresh introduced errors. Missing checker baselines never prevent editing; unknown findings remain unattributed. Stop/SubagentStop UI summaries do not prove model receipt.
+
+Automatic feedback contains at most five diagnostics and 2 KiB, under an 8 KiB per-agent/turn budget. Use diagnostics with run=cached and scope=session for details. Repeated delivery IDs may follow an ACK failure; ACK confirms stdout only. After a Hook-definition upgrade, ask the user to review /hooks and start a new session; never change Hook trust or existing automatic/gate choices. Hooks never apply plans.
+
+See [usage](../../docs/usage.md), [configuration](../../docs/usage.md#configuration), [limits](../../docs/usage.md#limits) and [upgrade](../../docs/usage.md#upgrade).

package/skills/setup-lsp/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: setup-lsp
+description: Configure, install or repair Codex CodeIntel language servers and project checkers for a project or explicitly requested global defaults. Use for setup tasks; ordinary coding with missing tools only needs a brief setup suggestion.
+---
+
+Set up working CodeIntel capabilities for the requested scope. The display name is **setupLSP** and invocation is **`$setup-lsp`**.
+
+1. Identify scope and conventions. Default to the current project; modify `$CODEX_HOME/lsp-client.json` (default `~/.codex/lsp-client.json`) only when the user requests global setup. Read both existing configurations, applicable repository instructions, language manifests, package-manager/lock files, environments, build files and representative source files. Do not read or change Codex directory trust records. Use the absolute project directory as `workspace`.
+2. Reuse explicit commands, nearest project environments and PATH tools, in that order. Check actual startup before replacing configuration. Repair/report a failing installed command at its current location; do not download another version as a fallback. Install missing tools within the chosen scope using the project's conventions: Python uses uv; Node respects the package manager and otherwise prefers pnpm. Reuse Rust toolchains and C/C++ build systems. If an installation fails, record the unavailable capability and continue independent languages. A system change outside the requested scope needs separate authorization; finish the other configuration work first.
+3. Merge configuration using [configuration.md](references/configuration.md). Preserve unrelated settings and explicitly disabled capabilities; arrays replace rather than merge in the plugin. Put reusable defaults in global configuration only for global setup, and project directories, checker commands and coverage in project configuration. New configurations enable nonblocking `postToolUse="delta"` and `stop="errors"` feedback. Preserve existing automatic-off choices. Never enable `stopGate` automatically, and never put it in project configuration.
+4. Cover the actual project using [languages.md](references/languages.md). Configure Python ty and Ruff independently, appropriate TypeScript LSP and type/lint checks for each package, Go module checks, Cargo workspace checks, and C/C++ compilation databases. Set coverage to the command's actual input set, including exclusions. If the C/C++ checker cannot emit supported JSON/SARIF, keep clangd capabilities and explain the project-check gap. A successful check of one source file does not establish whole-project coverage.
+5. Verify capabilities through the installed plugin. Call `status` with `refresh=true` and representative paths; it only resolves tools and reports state. Run `diagnostics` for those paths, exercise a read-only navigation operation such as definition or symbols, and run `check`, following structured `next` until finished. Diagnose pending, failed or uncovered results. Do not count `command -v` or `--version` alone as completion. Use an isolated fixture when the user project lacks a usable representative; state that verification limit. rename and format only generate plans; apply is the only source writer. Do not call apply unless the user authorized the corresponding edits.
+6. Report exact configuration paths changed, tools installed, verified capabilities, remaining gaps and recovery steps. Automatic feedback requires a current host with native async Hooks and Interrupt. After Hook definitions change, tell the user to review /hooks and start a new session; never modify Hook trust records. Subagents only report independently; only the main Stop may use the user's existing global gate. Partial setup is useful: an unavailable checker never prevents ordinary editing or verification of other languages.
+
+This skill is normally discoverable, but installation/configuration changes belong to setup, installation or repair requests. During ordinary coding, explain missing capability once and suggest `$setup-lsp`; continue the coding task without repeated installs, retries or a setup prerequisite.

package/skills/setup-lsp/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "setupLSP"
+  short_description: "Configure and verify project language tools"
+  default_prompt: "Use $setup-lsp to configure and verify CodeIntel tools for this project."

package/skills/setup-lsp/references/configuration.md

@@ -0,0 +1,33 @@
+# CodeIntel configuration
+
+Read `$CODEX_HOME/lsp-client.json` (or `~/.codex/lsp-client.json`) and `<workspace>/.codex/lsp-client.json`. Built-in defaults < global < project. Objects merge by field/language; arrays replace wholesale. Both files use `schemaVersion: 1`. Do not overwrite unrelated entries or user-off settings. A malformed existing file needs repair from its existing intent, not replacement with a default file.
+
+A new project feedback configuration can start with:
+
+```json
+{
+  "schemaVersion": 1,
+  "automaticDiagnostics": { "postToolUse": "delta", "stop": "errors" },
+  "projectChecks": "auto",
+  "lsp": { "python": "ty", "typescript": "typescript", "go": "gopls", "cpp": "clangd", "rust": "rust" },
+  "lint": { "python": "auto", "javascript": "auto" }
+}
+```
+
+Limit language additions to the project and preserve existing choices. No configuration means automatic feedback is off while all nine MCP tools remain explicitly callable. `automaticDiagnostics.stop="errors"` is feedback only. Ending gates require a separately authorized **global** `stopGate="introduced-errors"`; setup never enables it automatically. An existing global choice is preserved. Project `stopGate` is ignored. No plugin trust field or environment variable is required.
+
+LSP entries are a built-in name, `false`, or `{command: [program, ...args], extensions: [".ext"], env?: {KEY: "value"}, initialization?: {...}}`. Use `.py/.pyi`, `.ts/.tsx/.mts/.cts/.js/.jsx/.mjs/.cjs`, `.c/.h/.cpp/.hpp` and `.rs` as appropriate for custom servers; do not conflict with enabled built-in extensions. Explicit relative commands resolve from the workspace and never fall back. Built-ins resolve the nearest project environment, then PATH; automatic work never downloads missing tools.
+
+`lint.python` accepts `auto/ruff/off`; `lint.javascript` accepts `auto/biome/eslint/off`. Lint-off does not disable explicitly requested formatting. `formatting` accepts `tabSize` (1–16) and `insertSpaces`. `exclude` is an array of relative forward-slash globs, without `..`, absolute paths or negation.
+
+For multi-package or custom checks, replace `projectChecks` with the complete desired array. Each entry has a unique `name`, relative `cwd`, nonempty `command` array, `parser`, and nonempty `coverage` globs relative to that cwd. Relative command paths resolve from that cwd. Automatic commands must check without dependency installation or source modification. Output parsers: `tsc`, concise `ty`, JSON `go`/`cargo`, `ruff`, `eslint`, `biome`, `sarif`, and custom `json`:
+
+```json
+{
+  "diagnostics": [
+    { "path": "src/main.c", "line": 1, "column": 1, "severity": "error", "source": "compiler/rule", "message": "description" }
+  ]
+}
+```
+
+Diagnostic paths are relative to the check cwd; positions are 1-based. An empty custom result is `{"diagnostics":[]}`. Coverage must match actual inputs and exclusions, not merely desired coverage. Explicit checks replace automatic discovery, so keep needed checks for every language. See the [usage guide](../../../docs/usage.md#configuration) and [multi-package example](../../../docs/examples/lsp-client.project-checks.json).

package/skills/setup-lsp/references/languages.md

@@ -0,0 +1,40 @@
+# Language setup decisions
+
+Read only the relevant language guidance. Work in the requested project/global scope and verify with real MCP requests after configuration.
+
+## Python
+
+Reuse configured ty commands, package `.venv` executables and PATH installations; Ruff is a separate capability. For an existing uv project, missing project tools can use `uv add --dev ty ruff`, respecting its dependency groups and lockfile. For a project without a managed environment, use `uv venv .venv` then `uv pip install --python .venv/bin/python ty ruff` (use `.venv/Scripts/python.exe` on Windows). Explicit global setup can use `uv tool install ty` and `uv tool install ruff`. Do not synchronize or replace an existing environment merely to repair one executable. Respect the chosen Python version.
+
+Use `"python": "ty"`. Root `pyproject.toml` or `ty.toml` enables auto project type checking. For nested packages or custom scope, use separate checks:
+
+- Types: `[".venv/bin/ty", "check", "--output-format", "concise", "--color", "never"]`, parser `ty`.
+- Lint: `[".venv/bin/ruff", "check", "--no-fix", "--no-fix-only", "--output-format", "json", "src"]`, parser `ruff`.
+
+Set cwd to the package and coverage to its checked Python inputs, respecting ty/Ruff exclusions. Ruff failure should not remove ty diagnostics/navigation; ty failure should not prevent Ruff lint/formatting. Validate types and lint separately when one is missing. Do not infer repair authorization for formatting from a setup request.
+
+## TypeScript / JavaScript
+
+Read `packageManager`, lockfiles, workspace definitions and the effective tsconfig inputs/references. Keep the package manager. With no convention prefer `pnpm`. Choose the LSP that actually starts with the project's installed compiler: the built-in `typescript` uses `typescript-language-server --stdio`; `tsc` uses `tsc --lsp --stdio` and requires native LSP support (TypeScript 7+); `tsgo` requires that executable. An older or incompatible local compiler must be repaired explicitly rather than silently launching a downloaded replacement. Preserve project TypeScript version constraints.
+
+Install only missing project tools with the chosen manager (for example `pnpm add -D typescript-language-server`); global setup uses that manager's user-level global installation conventions. Select Biome or ESLint from existing configuration. Do not invent a new lint system if there is none. Reuse existing scripts only if they check without modifying source and produce a supported format.
+
+For a simple root tsconfig, auto checking reads its effective coverage. For references/multiple packages use explicit per-package type and lint checks. A typical type command is `["node_modules/.bin/tsc", "--noEmit", "--pretty", "false", "-p", "tsconfig.json"]` with parser `tsc`; use actual hoisted/Windows tool paths where appropriate. Biome uses `lint --reporter=json --max-diagnostics=none`; ESLint uses `--format json`. JS type coverage requires both `allowJs` and `checkJs`. Derive globs from each command's actual config, files, include and exclude. Verify representative files from each package.
+
+## Go
+
+Reuse the project's Go version, gopls, modules/workspaces and build flags. Configure `lsp.go="gopls"`; do not replace the module/toolchain to make setup pass. A root go.mod enables `go vet -mod=readonly -json ./...` with parser `go`. Automatic scope is derived from `go list` Go/Test inputs, including platform and build-tag selection. Multi-module workspaces or custom tags require explicit commands and accurate coverage. Prepare dependencies intentionally during setup; automatic checks disable toolchain and module downloads. Verify real diagnostics, definitions/references, and rename/format plans on representative files; apply only if the user authorized modifying them.
+
+## Rust
+
+Reuse `rust-analyzer`, Cargo, rust-src and the pinned Rustup toolchain. Install missing components within the requested toolchain scope only; avoid a workspace toolchain change as a setup shortcut. Root Cargo auto checking uses `cargo check --workspace --all-targets --message-format=json`. Nested workspaces or special features need explicit checks with their actual cwd, flags and coverage. Prepare dependencies intentionally during setup if needed. Automatic checks disable Rustup auto-install; a missing pinned toolchain remains unavailable. Verify actual diagnostics and navigation after indexing, and CLI checking of the workspace. Explain feature or platform coverage limitations.
+
+## C / C++
+
+Reuse clangd and the configured Clang/LLVM or project toolchain. Reuse `compile_commands.json`; if absent, generate it through the project's existing CMake/Meson/other build process with the project's build options. A fallback `compile_flags.txt` is appropriate only when it matches the actual build. Supply clangd's `--compile-commands-dir` via an explicit custom entry if the database is in an undiscovered build directory.
+
+Project checks need structured JSON/SARIF output from a real compiler/checker or an existing read-only wrapper. For a single translation unit on a compatible Clang, `clang -fsyntax-only -fdiagnostics-format=sarif -Wno-sarif-format-unstable` plus the actual compile flags may work with parser `sarif`; restrict coverage to the checked files/headers. Do not concatenate multiple SARIF JSON documents or claim a representative command covers the entire build. Prefer the project's structured checking path for a full build. If unavailable, keep clangd diagnostics/navigation and explain the project-check and reliable-baseline gap. Do not require a new system LLVM installation to finish unrelated language setup.
+
+## Mixed projects and offline failures
+
+Configure each package's cwd and real input coverage. A checker failing in one language does not cancel verification of other languages. Preserve working local tools. If an offline install fails, stop retrying that install, retain usable configuration and explicitly report the missing capability; do not disable the whole workspace or turn on a gate. Verify in isolated project and `CODEX_HOME` directories when evaluating setup examples, so user global configuration remains untouched.