kimi-plugin-cc 2.2.2 → 2.4.0

package/.claude-plugin/marketplace.json

@@ -4,8 +4,8 @@
     "name": "linxule"
   },
   "metadata": {
-    "description": "Kimi for Claude Code: code questions, reviews, fixes, and parallel tasks through the local Kimi Code CLI.",
-    "version": "2.2.2"
+    "description": "Kimi for Claude Code: code questions, reviews, fixes, parallel tasks, and MCP tasks through the local Kimi Code CLI.",
+    "version": "2.4.0"
   },
   "plugins": [
     {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kimi",
-  "description": "Claude Code plugin that delegates read-only review, challenge, free-form ask, and write-capable rescue work to the local kimi-code CLI. Includes an opt-in stop-time review gate and a PreToolUse hook that enforces per-command safety.",
-  "version": "2.2.2",
+  "description": "Kimi for Claude Code: code questions, independent reviews, bounded fixes, autonomous goals, parallel tasks, and MCP tasks through the local Kimi Code CLI, with PreToolUse safety hooks.",
+  "version": "2.4.0",
   "homepage": "https://github.com/linxule/kimi-plugin-cc",
   "repository": "https://github.com/linxule/kimi-plugin-cc",
   "license": "Apache-2.0",
@@ -11,7 +11,9 @@
     "review",
     "code-review",
     "delegation",
-    "multi-model"
+    "multi-model",
+    "mcp",
+    "model-context-protocol"
   ],
   "author": {
     "name": "linxule"

package/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "kimi": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/scripts/companion.sh",
+      "args": [
+        "mcp"
+      ],
+      "env": {
+        "KIMI_PLUGIN_CC_MCP_WORKSPACE": "${CLAUDE_PROJECT_DIR}"
+      }
+    }
+  }
+}

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 > **Post-1.0 release history (v1.0.1 -> present) lives in [ROADMAP-TO-GA.md § Post-GA audit log](./ROADMAP-TO-GA.md#post-ga-audit-log)** and the "Version" / "Upstream compat" lines of [AGENTS.md](./AGENTS.md). Docs-only kimi-code compat checkups that don't bump the plugin version (e.g. the 0.14.2 / 0.14.3 patches) are recorded there, not here. Notable releases are summarized below; the GA entry and full pre-GA detail follow.
 
+## 2.4.0 — 2026-10-24
+
+- Add one dependency-free MCP stdio server for Claude Code and Codex, with typed schemas for seven model operations plus job status, result, and cancellation. The existing slash commands, skills, safety hooks, and review gate remain intact.
+- Return native MCP task handles for Claude calls that negotiate the tasks extension per request. Codex receives ordinary launch handles and uses explicit job-control tools; this does not claim native task-extension support for Codex.
+- Supervise each operation through a fixed task/job UUID, bounded attachment, durable reconnects, and PID/PGID/start-token identity checks. Preserve recoverable launches and their public IDs after inconclusive probes, reconcile stale dead companions, and keep cancellation from signalling a changed identity.
+- Preserve exact CLI 2.3.1 certification, workspace containment, data-root isolation, hook verification, resume lineage, and trusted write roots. Terminal jobs retain their artifact semantics: failed jobs complete tasks with `isError:true`, and cancelled jobs map to `cancelled`.
+- Document the transport, lifecycle, ownership, safety, comment-hygiene, and contributor rules. Align package and marketplace descriptions and keywords with the MCP surface.
+
+Contributors: **Kimi** (design, implementation, documentation, and verification), **Claude** and **Codex** (adversarial review and re-review).
+
+## 2.3.1 — 2026-10-23
+
+- Certify exact kimi-code 2.3.1 for all eight native-v2 operations after the source scan, plan-ON/OFF controls and full 15-test candidate smoke. Preserve the no-plan construction and document the new session-lock, internal-`ps`/PATH and legacy-trust-migration residuals. See [evidence](docs/upstream-2.3.1-certification.md).
+- Give Kimi clearer operation-specific contracts: evidence-backed ask/review/challenge responses, complete rescue implementation and verification, honest pursue budgets, and a host-neutral, evidence-only review gate. Keep raw task text in job summaries and fallback titles while the full prompt drives execution and recovery.
+- Include untracked files in working-tree reviews, keep `--base` snapshots isolated from dirty files, and make truncated-diff coverage explicit. Pursue now uses `/goal --` and enforces the 4000-character objective budget including injected guidance; swarm prompts distinguish soft total counts, hard concurrency and prompt-only coordination.
+- Remove roughly 2,300 lines of stale or duplicated release archaeology from production comments while retaining current safety invariants. Capture the durable prompt, scope, comment-hygiene and release rules in `AGENTS.md`, `CONTRIBUTING.md` and the compatibility docs.
+- Make missing-session-ID warnings distinguish resume from replay, and fail write-swarm patch capture explicitly when intent-to-add fails instead of silently omitting new files. Capture failures now fail the job and retain the worktree for recovery; successful runs preserve the `[swarm-write]` summary prefix.
+
 ## 2.2.2 — 2026-10-22
 
 - Certify exact kimi-code 2.3.0 for all eight native-v2 operations after its

package/README.md

@@ -40,7 +40,7 @@ You need:
 - macOS or Linux
 - Claude Code or Codex with plugin support
 - Node.js 22.5 or newer
-- Kimi Code CLI 2.3.0 (2.2.0 also certified), the recommended version for plugin 2.2.2
+- Kimi Code CLI 2.3.1 (2.3.0 also certified), the recommended version for plugin 2.4.0
 
 Windows is not currently supported. Check your versions in a terminal:
 
@@ -108,7 +108,7 @@ needed to use the package. Kimi Code CLI and Node are still prerequisites.
 For an explicitly versioned local Claude Code plugin:
 
 ```sh
-npm install --prefix ~/.local/share/kimi-plugin-cc kimi-plugin-cc@2.2.2
+npm install --prefix ~/.local/share/kimi-plugin-cc kimi-plugin-cc@2.4.0
 claude --plugin-dir ~/.local/share/kimi-plugin-cc/node_modules/kimi-plugin-cc
 ```
 
@@ -180,6 +180,19 @@ Canceling a task does not undo changes it has already made.
 
 Ask and rescue support resuming a session. For example, `/kimi:ask -r Explain the next step.` continues your latest ask session. In Codex, ask `$kimi-ask` to resume it. See the [ask options](./commands/ask.md) and [rescue options](./commands/rescue.md).
 
+### Use the MCP server
+
+The plugin also bundles one MCP stdio server for Claude Code and Codex, alongside the existing slash commands and skills. Those interfaces remain available, and the existing safety-hook setup is still mandatory.
+
+The seven model tools are `kimi_ask`, `kimi_review`, `kimi_challenge`, `kimi_rescue`, `kimi_pursue`, `kimi_swarm`, and `kimi_swarm_write`. Job control uses `kimi_job_status`, `kimi_job_result`, and `kimi_job_cancel`.
+
+- **Claude Code:** task-capable calls return durable MCP tasks. Poll them with `tasks/get` and cancel them with `tasks/cancel`.
+- **Codex:** calls currently use ordinary MCP results, not native MCP tasks. After attachment, a running job returns a launch handle; an already settled job returns its terminal result. Use the three job-control tools to check, read, or cancel it.
+
+Claude supplies the project directory as the default workspace. When the host has no default, as is normal for Codex, the initial operation requires an absolute `workspace` path. Later job-control calls can rely on the job's persisted workspace binding. An MCP server disconnect does not cancel jobs. The jobs table owns status and outcomes; the terminal artifact is the result authority. Failed jobs return `isError: true` with their artifacts.
+
+For example: “Use `kimi_review` to check this diff. In Claude Code, poll the returned task with `tasks/get`; in Codex, use the returned handle with `kimi_job_status` and then `kimi_job_result`.”
+
 ## Update or remove the plugin
 
 ### Update in Claude Code
@@ -249,7 +262,7 @@ Contributors need Bun to run `bun run check`. The detailed engineering documents
 - macOS 或 Linux
 - 支持插件的 Claude Code 或 Codex
 - Node.js 22.5 或更高版本
-- Kimi Code CLI 2.3.0（2.2.0 亦已认证），这是插件 2.2.2 的推荐版本
+- Kimi Code CLI 2.3.1（2.3.0 亦已认证），这是插件 2.4.0 的推荐版本
 
 目前不支持 Windows。在终端检查版本：
 
@@ -364,6 +377,19 @@ Claude Code 还提供可选的[自动审查功能](./commands/setup.md)，在 Cl
 
 Ask 和 rescue 支持恢复会话。例如，`/kimi:ask -r 解释下一步。` 会继续最近一次 ask 会话。在 Codex 中，请 `$kimi-ask` 恢复该会话。参见 [ask 参数](./commands/ask.md)和 [rescue 参数](./commands/rescue.md)。
 
+### 使用 MCP 服务器
+
+插件现在还内置了一个同时供 Claude Code 和 Codex 使用的 MCP stdio 服务器，与现有斜杠命令和技能并存。这些界面仍然可用，现有的安全钩子配置也仍是必需步骤。
+
+七个模型工具是 `kimi_ask`、`kimi_review`、`kimi_challenge`、`kimi_rescue`、`kimi_pursue`、`kimi_swarm` 和 `kimi_swarm_write`。任务控制使用 `kimi_job_status`、`kimi_job_result` 和 `kimi_job_cancel`。
+
+- **Claude Code：** 支持任务式调用的工具会返回持久 MCP 任务，通过 `tasks/get` 轮询，通过 `tasks/cancel` 取消。
+- **Codex：** 目前使用普通 MCP 结果，而不是原生 MCP 任务。附加完成后，仍在运行的任务返回启动句柄；已结束的任务直接返回最终结果。使用上述三个任务控制工具查看进度、读取结果或取消任务。
+
+Claude 默认提供项目目录作为工作区。如果宿主没有默认工作区（Codex 通常如此），首次操作必须提供绝对的 `workspace` 路径。之后的任务控制调用可以使用为该任务保存的工作区绑定关系。MCP 服务器断开连接不会取消任务。`jobs` 表是任务状态与结局的依据，最终产物（artifact）是结果内容的依据。任务失败时会返回 `isError: true` 以及相应产物。
+
+例如：“使用 `kimi_review` 检查这次差异。在 Claude Code 中，用 `tasks/get` 轮询返回的任务；在 Codex 中，用返回的句柄调用 `kimi_job_status`，然后调用 `kimi_job_result`。”
+
 ## 更新或移除插件
 
 ### 在 Claude Code 中更新
@@ -433,7 +459,7 @@ Il vous faut :
 - macOS ou Linux
 - une version de Claude Code ou de Codex prenant en charge les plugins
 - Node.js 22.5 ou une version ultérieure
-- Kimi Code CLI 2.3.0 (2.2.0 également certifiée), la version recommandée pour le plugin 2.2.2
+- Kimi Code CLI 2.3.1 (2.3.0 également certifiée), la version recommandée pour le plugin 2.4.0
 
 Windows n'est pas pris en charge actuellement. Vérifiez les versions dans un terminal :
 
@@ -548,6 +574,19 @@ Annuler une tâche n'annule pas les modifications déjà effectuées.
 
 Ask et rescue permettent de reprendre une session. Par exemple, `/kimi:ask -r Explique l'étape suivante.` reprend votre dernière session ask. Dans Codex, demandez à `$kimi-ask` de la reprendre. Consultez les [options d'ask](./commands/ask.md) et les [options de rescue](./commands/rescue.md).
 
+### Utiliser le serveur MCP
+
+Le plugin intègre aussi un serveur MCP stdio unique pour Claude Code et Codex, en plus des commandes slash et skills existants. Ces interfaces restent disponibles et la configuration du hook de sécurité reste obligatoire.
+
+Les sept outils de modèle sont `kimi_ask`, `kimi_review`, `kimi_challenge`, `kimi_rescue`, `kimi_pursue`, `kimi_swarm` et `kimi_swarm_write`. Le contrôle des tâches utilise `kimi_job_status`, `kimi_job_result` et `kimi_job_cancel`.
+
+- **Claude Code :** les appels compatibles avec les tâches renvoient des tâches MCP durables. Interrogez-les avec `tasks/get` et annulez-les avec `tasks/cancel`.
+- **Codex :** les appels utilisent actuellement des résultats MCP ordinaires, et non des tâches MCP natives. Après l'attachement, un job encore actif renvoie un handle de lancement ; un job déjà terminé renvoie directement son résultat final. Utilisez les trois outils de contrôle pour suivre, lire ou annuler le job.
+
+Claude fournit le répertoire du projet comme espace de travail par défaut. Sans espace de travail par défaut côté hôte, ce qui est normal pour Codex, l'opération initiale exige un chemin `workspace` absolu. Les contrôles ultérieurs peuvent utiliser l'association enregistrée entre la tâche et l'espace de travail. Une déconnexion du serveur MCP n'annule pas les tâches. La table jobs fait autorité pour l'état et l'issue des jobs ; l'artefact final fait autorité pour le contenu du résultat. Une tâche en échec renvoie `isError: true` avec ses artefacts.
+
+Par exemple : « Utilise `kimi_review` pour vérifier ce diff. Dans Claude Code, interroge la tâche renvoyée avec `tasks/get` ; dans Codex, utilise le handle renvoyé avec `kimi_job_status`, puis `kimi_job_result`. »
+
 ## Mettre à jour ou supprimer le plugin
 
 ### Mettre à jour dans Claude Code
@@ -617,7 +656,7 @@ Les contributeurs ont besoin de Bun pour exécuter `bun run check`. La documenta
 - macOS または Linux
 - プラグインに対応した Claude Code または Codex
 - Node.js 22.5 以降
-- Kimi Code CLI 2.3.0（2.2.0 も認証済み。プラグイン 2.2.2 の推奨バージョン）
+- Kimi Code CLI 2.3.1（2.3.0 も認証済み。プラグイン 2.4.0 の推奨バージョン）
 
 現在、Windows には対応していません。ターミナルでバージョンを確認します。
 
@@ -732,6 +771,19 @@ Codex では「$kimi-review を使い、設定済みの『……』というモ
 
 Ask と rescue はセッションの再開に対応しています。たとえば `/kimi:ask -r 次の手順を説明してください。` は、直近の ask セッションを続けます。Codex では `$kimi-ask` に再開を依頼してください。[ask のオプション](./commands/ask.md)と [rescue のオプション](./commands/rescue.md)を参照できます。
 
+### MCP サーバーを使う
+
+プラグインには、既存のスラッシュコマンドとスキルに加え、Claude Code と Codex の両方で使える MCP stdio サーバーが 1 つ同梱されています。既存のコマンドとスキルも引き続き使え、既存の安全フックの設定も必須です。
+
+7 つのモデルツールは `kimi_ask`、`kimi_review`、`kimi_challenge`、`kimi_rescue`、`kimi_pursue`、`kimi_swarm`、`kimi_swarm_write` です。ジョブ制御には `kimi_job_status`、`kimi_job_result`、`kimi_job_cancel` を使います。
+
+- **Claude Code：** タスク対応の呼び出しは永続的な MCP タスクを返します。`tasks/get` でポーリングし、`tasks/cancel` でキャンセルします。
+- **Codex：** 現在はネイティブの MCP タスクではなく、通常の MCP 結果を使います。アタッチ後、実行中のジョブには起動ハンドルを返し、すでに終了したジョブには最終結果を直接返します。進捗確認・結果取得・キャンセルには 3 つのジョブ制御ツールを使います。
+
+Claude はプロジェクトディレクトリをデフォルトのワークスペースとして提供します。ホスト側にデフォルトがない場合（Codex ではこれが通常です）、最初の操作では絶対パスの `workspace` が必要です。後続のジョブ制御では、そのジョブに保存されたワークスペースの関連付けを利用できます。MCP サーバーとの接続が切れても、ジョブはキャンセルされません。`jobs` テーブルがジョブの状態と結果を管理し、最終成果物（artifact）が結果内容の正規の情報源となります。失敗したジョブも成果物とともに `isError: true` を返します。
+
+例：「`kimi_review` でこの差分を確認してください。Claude Code では返されたタスクを `tasks/get` でポーリングし、Codex では返されたハンドルを使って `kimi_job_status`、`kimi_job_result` の順に呼び出してください。」
+
 ## プラグインを更新または削除する
 
 ### Claude Code で更新する

package/agents/kimi-challenge.md

@@ -1,6 +1,6 @@
 ---
 name: kimi-challenge
-description: Use this agent when Claude wants Kimi to run an adversarial review that challenges the implementation approach, design choices, tradeoffs, and assumptions rather than just flagging defects. Choose this agent when the user wants pushback on whether the chosen approach is the right one, not a tighter pass over implementation defects (see kimi-review for that).
+description: Use this agent when the user or main thread wants Kimi to run an adversarial review that challenges the implementation approach, design choices, tradeoffs, and assumptions rather than just flagging defects. Choose this agent when the user wants pushback on whether the chosen approach is the right one, not a tighter pass over implementation defects (see kimi-review for that).
 model: sonnet
 tools: Bash
 color: yellow
@@ -21,7 +21,7 @@ Why this triggers: The user is asking for the alternative-perspective framing, n
 </example>
 
 <example>
-Context: The main Claude thread has just made a non-obvious design choice and the user says, "Stress test this."
+Context: The main thread has just made a non-obvious design choice and the user says, "Stress test this."
 Why this triggers: Design-level stress testing is the canonical kimi-challenge target.
 </example>
 
@@ -46,7 +46,7 @@ When invoked:
 - call the shared companion runtime with one Bash invocation after any model-discovery step: `${CLAUDE_PLUGIN_ROOT}/scripts/companion.sh task challenge <args>`
 - if the companion reports `CHALLENGE_HOOK_NOT_INSTALLED`, surface the refusal and tell the user to run `/kimi:setup`; do not reach for `KIMI_PLUGIN_CC_SKIP_HOOK_CHECK`
 - the companion accepts a **strict allowlist** of flags: `--thinking <off|low|medium|high>` (requested per run), `--base <ref>`, `-m`/`--model <name>`, `--budget <dur>`. Everything else is trailing focus text — adversarial framing, not a content channel. Reasoning behavior follows the selected model and Kimi configuration unless `--thinking <effort>` requests one for this run (honoured by Kimi's own providers on models that can turn thinking off; other providers ignore it silently; the plugin cannot verify it). `--no-thinking` is rejected; use `--thinking off`
-- do not invent flags (`--file`, `--context`, `--path`, etc.). The runtime hard-fails with `INVALID_ARGS` on unknown flag-shaped tokens. If you need to attach file content or extended context, switch to `kimi-ask` or paste a brief summary into the focus text — challenge's payload is the git diff, not arbitrary file content
+- do not invent flags (`--file`, `--context`, `--path`, etc.). The runtime hard-fails with `INVALID_ARGS` on unknown flag-shaped tokens. If you need to attach file content or extended context, switch to `kimi-ask` or paste a brief summary into the focus text — challenge's payload is the git diff plus untracked files listed by `git status` for working-tree challenges, or only the branch/commit diff with `--base` — not arbitrary file content
 - do not pass `--background` or `--wait` to the companion — the runtime rejects both with `INVALID_FLAGS` for review and challenge
 - if the user wants fire-and-forget behavior on a broad challenge, detach the Bash call itself with `run_in_background: true` instead of reaching for a companion flag; after launching, tell the user to check `/kimi:status` for progress
 - `/kimi:result <jobId> --json` returns a structured envelope with metadata plus the artifact body.

package/agents/kimi-pursue.md

@@ -47,7 +47,7 @@ When invoked:
 - decide whether the task is genuinely AUTONOMOUS multi-turn pursuit rather than a single bounded delegated task (kimi-rescue) or read-only work (kimi-ask / kimi-review / kimi-swarm); when in doubt, prefer kimi-rescue — pursue is only for explicit hands-off autonomy
 - preserve the user's objective and explicit constraints with minimal reframing
 - call the shared companion runtime with one Bash invocation after any model-discovery step: `${CLAUDE_PLUGIN_ROOT}/scripts/companion.sh task pursue <args>`
-- the companion accepts a **strict allowlist** of flags: `--thinking <off|low|medium|high>` (requested per run), `--budget <duration>` (HARD wall-clock ceiling; e.g. `30m`, `1h`, `90s`; bare number = minutes; default 45m — the ONLY guaranteed bound on an autonomous run), `--turns <N>` (SOFT hint injected into the objective so Kimi calls `SetGoalBudget` itself; advisory, NOT enforced headless), and `-m`/`--model <name>`. Everything else is trailing objective text. Reasoning behavior follows the selected model and Kimi configuration unless `--thinking <effort>` requests one for this run (honoured by Kimi's own providers on models that can turn thinking off; other providers ignore it silently; the plugin cannot verify it). `--no-thinking` is rejected; use `--thinking off`
+- the companion accepts a **strict allowlist** of flags: `--thinking <off|low|medium|high>` (requested per run), `--budget <duration>` (HARD wall-clock ceiling; e.g. `30m`, `1h`, `90s`; bare number = minutes; default 45m — the ONLY guaranteed bound on an autonomous run), `--turns <N>` (SOFT instruction injected into the objective to stop after at most N turns, NEVER a request to call the denied `SetGoalBudget` tool; advisory, NOT enforced headless, and a soft stop is NOT proof of completion), and `-m`/`--model <name>`. Everything else is trailing objective text. Reasoning behavior follows the selected model and Kimi configuration unless `--thinking <effort>` requests one for this run (honoured by Kimi's own providers on models that can turn thinking off; other providers ignore it silently; the plugin cannot verify it). `--no-thinking` is rejected; use `--thinking off`
 - do not invent flags. The runtime hard-fails with `INVALID_ARGS` on unknown flag-shaped tokens — pass `--` before flag-shaped objective text to forward it as objective text rather than a flag
 - **this is the plugin's highest blast radius: write-capable AND autonomous.** Only dispatch on explicit user intent for hands-off multi-turn pursuit. Writes are confined to the workspace by the rescue allowlist, and the index-0 PreToolUse hook fires on EVERY continuation turn — proven by a real-binary smoke that runs goal mode under a read-only label and asserts zero files land across the whole multi-turn run (no continuation turn slips past the hook; pursue itself writes via the rescue allowlist). pursue cannot mutate git state (the main thread owns branch/commit). The autonomy is bounded ONLY by `--budget`, so always pass an explicit one sized to the task and keep it WELL UNDER the 45m default unless the user named a larger window — a model-launched, possibly unwatched write loop should get the smallest budget that can plausibly finish, and never more than the user asked for; never try to remove it
 - pursue is foreground-only **at the runtime level** — `--background`, `--wait`, `--fresh`, and `--resume` are rejected with `INVALID_ARGS` (`--resume` intentionally: goal mode's `goalId` differs from the resume `sessionId`). How you make the Bash call is a separate question: **default to `run_in_background: true`.** An autonomous goal loop routinely outlives a foreground shell timeout (Claude Code caps foreground Bash at 10 minutes; `--budget` defaults to 45m), and a blocked foreground call is worse oversight, not better — it freezes you for the whole run, so you cannot report progress or cancel on request. What bounds this surface is the managed PreToolUse hook, the workspace allowlist, the no-git-mutation rule, and the mandatory finite `--budget` — none of which depend on anyone watching. Keep `--budget` finite and never remove it: it is the sole hard bound on the loop

package/agents/kimi-rescue.md

@@ -1,6 +1,6 @@
 ---
 name: kimi-rescue
-description: Use this agent proactively when the user wants to delegate a substantial investigation or implementation task to Kimi, especially multi-step bug hunts, cross-file refactors, or work the main Claude thread would rather offload than context-switch through. Choose this agent when the work is too large for an inline response but the user clearly wants it handed off, not just reviewed.
+description: Use this agent proactively when the user wants to delegate a substantial investigation or implementation task to Kimi, especially multi-step bug hunts, cross-file refactors, or work the main thread would rather offload than context-switch through. Choose this agent when the work is too large for an inline response but the user clearly wants it handed off, not just reviewed.
 model: sonnet
 tools: Bash
 color: magenta
@@ -26,7 +26,7 @@ Why this triggers: The user is clearly asking to resume a prior Kimi rescue work
 </example>
 
 <example>
-Context: The main Claude thread has been debugging a multi-file runtime error for several turns, the investigation has grown beyond inline reasoning, and the user has not yet explicitly asked for delegation.
+Context: The main thread has been debugging a multi-file runtime error for several turns, the investigation has grown beyond inline reasoning, and the user has not yet explicitly asked for delegation.
 Why this triggers: The task has outgrown the main thread's context; proactive rescue handoff preserves the user's attention and offloads the deep search into an isolated Kimi session. Proactive rescue is for a SINGLE bounded handoff of in-flight work — if the user wants Kimi to keep driving toward an objective on its own across many turns, that is autonomous goal mode and needs explicit intent (see kimi-pursue), not rescue's proactive path.
 </example>
 

package/agents/kimi-review.md

@@ -1,6 +1,6 @@
 ---
 name: kimi-review
-description: Use this agent when Claude wants an independent second-pair-of-eyes review from Kimi over a working-tree diff or branch diff. Choose this agent for read-only diff review — multi-file changes, design-risk changes, or when the user explicitly asks for another reviewer. Not for implementation work (see kimi-rescue) or free-form Q&A (see kimi-ask).
+description: Use this agent when the user or main thread wants an independent second-pair-of-eyes review from Kimi over working-tree changes, including untracked files listed by `git status`, or a branch diff. Choose this agent for read-only change review — multi-file changes, design-risk changes, or when the user explicitly asks for another reviewer. Not for implementation work (see kimi-rescue) or free-form Q&A (see kimi-ask).
 model: sonnet
 tools: Bash
 color: cyan
@@ -16,7 +16,7 @@ Why this triggers: The user is explicitly asking for a second reviewer from Kimi
 </example>
 
 <example>
-Context: The main Claude thread just finished a multi-file refactor and the user says, "Does this hold up?"
+Context: The main thread just finished a multi-file refactor and the user says, "Does this hold up?"
 Why this triggers: Multi-file, risk-bearing change where a cross-model reviewer adds value over another pass from the same thread.
 </example>
 
@@ -46,7 +46,7 @@ When invoked:
 - call the shared companion runtime with one Bash invocation after any model-discovery step: `${CLAUDE_PLUGIN_ROOT}/scripts/companion.sh review <args>`
 - if the companion reports `REVIEW_HOOK_NOT_INSTALLED`, surface the refusal and tell the user to run `/kimi:setup`; do not reach for `KIMI_PLUGIN_CC_SKIP_HOOK_CHECK`
 - the companion accepts a **strict allowlist** of flags: `--thinking <off|low|medium|high>` (requested per run), `--base <ref>`, `-m`/`--model <name>`, `--budget <dur>`. Everything else is trailing focus text — a short scope hint, not a content channel. Reasoning behavior follows the selected model and Kimi configuration unless `--thinking <effort>` requests one for this run (honoured by Kimi's own providers on models that can turn thinking off; other providers ignore it silently; the plugin cannot verify it). `--no-thinking` is rejected; use `--thinking off`
-- do not invent flags (`--file`, `--context`, `--path`, etc.). The runtime hard-fails with `INVALID_ARGS` on unknown flag-shaped tokens. If you need to attach file content or extended context, switch to `kimi-ask` or paste a brief summary into the focus text — review's payload is the git diff, not arbitrary file content
+- do not invent flags (`--file`, `--context`, `--path`, etc.). The runtime hard-fails with `INVALID_ARGS` on unknown flag-shaped tokens. If you need to attach file content or extended context, switch to `kimi-ask` or paste a brief summary into the focus text — review's payload is the git diff plus untracked files listed by `git status` for working-tree reviews, or only the branch/commit diff with `--base` — not arbitrary file content
 - do not pass `--background` or `--wait` to the companion — the runtime rejects both with `INVALID_FLAGS` for review and challenge
 - if the user wants fire-and-forget behavior on a long review (multi-file diff, unclear scope), detach the Bash call itself with `run_in_background: true` instead of reaching for a companion flag; after launching, tell the user to check `/kimi:status` for progress
 - `/kimi:result <jobId> --json` returns a structured envelope with metadata plus the artifact body.

package/commands/README.md

@@ -1,6 +1,6 @@
-# Claude Code commands
+# Kimi task commands
 
-These Markdown files route Claude Code commands through `scripts/companion.sh` to the Node runtime. They also describe supported flags and model-selection rules. Codex uses the generated skills in `plugins/kimi-codex/skills/`.
+These Markdown files expose Kimi's ask, review, challenge, rescue, pursue, and swarm capabilities as Claude Code commands, routed through `scripts/companion.sh` to the Node runtime and local Kimi Code CLI. They also describe supported flags and model-selection rules. Codex uses the generated skills in `plugins/kimi-codex/skills/`.
 
 | File | Purpose |
 | --- | --- |

package/commands/challenge.md

@@ -14,7 +14,7 @@ Supported flags:
 
 - `--budget <dur>` — wall-clock ceiling (default 30m; `30m`, `1h`, `90s`, or bare minutes; maximum 24h)
 
-- `--base <ref>` — challenge against a branch/commit diff instead of the working tree
+- `--base <ref>` — challenge against a branch/commit diff instead of the working tree. Working-tree challenges also include untracked files listed by `git status`; `--base` remains branch/commit-diff only.
 - `-m`, `--model <name>`
 - trailing text — adversarial focus or framing to steer the challenge
 

package/commands/pursue.md

@@ -15,7 +15,7 @@ Supported flags:
 - `--thinking <off|low|medium|high>` (also `--thinking=<effort>`) — request effort for this process; other model-supported effort tokens pass through. `--no-thinking` is rejected; use `--thinking off`.
 
 - `--budget <duration>` — HARD wall-clock ceiling (e.g. `30m`, `1h`, `90s`; bare number = minutes). Default 45m. This is the only guaranteed bound on an autonomous run.
-- `--turns <N>` — SOFT cap: injected into the objective as a model instruction to call `SetGoalBudget`. Advisory, not enforced.
+- `--turns <N>` — SOFT instruction injected into the objective to stop after at most N turns; it never requests the denied `SetGoalBudget` tool. Advisory, not enforced; a soft stop is not proof the objective is complete. The plugin's `--budget` wall-clock ceiling remains the hard bound.
 - `-m`, `--model <name>`
 
 Prototype limitations (experimental):

package/commands/review.md

@@ -14,7 +14,7 @@ Supported flags:
 
 - `--budget <dur>` — wall-clock ceiling (default 30m; `30m`, `1h`, `90s`, or bare minutes; maximum 24h)
 
-- `--base <ref>` — review against a branch/commit diff instead of the working tree
+- `--base <ref>` — review against a branch/commit diff instead of the working tree. Working-tree reviews also include untracked files listed by `git status`; `--base` remains branch/commit-diff only.
 - `-m`, `--model <name>`
 - trailing text — optional focus hint for the review
 

package/dist/background-spawn.js

@@ -15,24 +15,16 @@ const companionEntrypoint = fileURLToPath(new URL(isCompiledRuntime ? "./compani
 const companionProjectRoot = path.resolve(path.dirname(companionEntrypoint), "..");
 const FAILURE_PERSIST_RETRY_DELAYS_MS = [100, 200, 400];
 export async function startBackgroundJob(job, prompt, context, paths, options) {
-    // MUST be the same resolution the hook verifier uses. The worker re-verifies
-    // the hook (rescue.ts / ask.ts, deliberately, so a background job cannot
-    // outlive or bypass the check), and the verifier rebuilds the canonical
-    // command from ITS OWN `process.argv0`. Spawning with a different spelling of
-    // node than setup pinned makes the worker compute a different expected
-    // command than the config holds → byte-exact mismatch → every background
-    // rescue/ask refuses forever, with `/kimi:setup` unable to converge the two
-    // sides (setup runs via companion.sh, whose argv0 is the stable symlink).
+    // Background spawn and hook verification must resolve the same stable Node
+    // path: the worker re-verifies the byte-exact hook command from its own
+    // runtime path, so a different spelling than setup pinned fails closed. For
+    // example, spawn(process.execPath) can resolve …/Cellar/node/<ver>/bin/node
+    // while setup pinned /opt/homebrew/bin/node.
     //
-    // Concretely: `spawn(process.execPath)` gives the child an argv0 equal to the
-    // fully symlink-resolved path (…/Cellar/node/<ver>/bin/node), whereas setup
-    // pins /opt/homebrew/bin/node. Caught by Kimi's pre-release review of v1.9.0.
-    // NOTE: this is deliberately NOT `resolveNodeBinary`, which additionally
-    // REQUIRES an absolute override because the hook command runs under
-    // `/bin/sh -c` with a possibly sanitized PATH. Spawning has no such
-    // constraint — a bare name is resolved by spawn() via PATH — so the override
-    // is honored verbatim here. Only the no-override default needs to change:
-    // it must match what the verifier computes, hence `preferStableNodePath`.
+    // An explicit spawn override need not be absolute because spawn() resolves
+    // bare names through PATH. The hook command separately requires an absolute
+    // override because /bin/sh -c may have a sanitized PATH. Only the no-override
+    // default uses preferStableNodePath to match the verifier.
     const override = context.env.KIMI_PLUGIN_CC_NODE_BIN;
     const nodeBinary = override !== undefined && override.length > 0
         ? override

package/dist/cli-client.js

@@ -1,17 +1,5 @@
 // Subprocess client for `kimi -p --output-format stream-json`.
 //
-// Replaces runtime/wire/client.ts for v1.0. Both modules coexist during the
-// PR 1-3 transition; PR 4 deletes wire/. The contract is intentionally
-// narrower than the v0.4 wire client — one process per prompt, no in-band
-// approvals (PreToolUse hook handles those), no resumable JSON-RPC channel.
-//
-// Where v0.4 streamed turn events to a TurnCapture state machine,
-// stream-json gives us flattened OpenAI-shaped records that callers
-// reassemble at their own seam. The buffered result is the primary return
-// shape; callers needing incremental visibility (e.g., updating SQLite
-// phase as tools run) can pass `onRecord` to observe records as they arrive
-// without paying for a separate event-stream API.
-//
 // Per-job env (`KIMI_PLUGIN_CC_CMD`) is set on this spawn so the
 // PreToolUse hook can branch per command (review vs rescue vs ask). It is
 // passed via the spawn `env` option, not exported to a shell, so concurrent
@@ -32,12 +20,7 @@ import { collectDescendantIdentities, revalidateProcessIdentities, waitForProces
 const STDERR_TAIL_BYTES = 8192;
 /** Hard cap on awaiting diagnostics log drain before resolving the result. */
 const LOG_DRAIN_TIMEOUT_MS = 250;
-/**
- * Default delay between SIGTERM and SIGKILL when an abort fires.
- * Matches v0.4's `cancellation.ts` escalation timing for wire clients,
- * so rescue/ask/review continue to feel identical to a stuck-kimi user
- * after the v1.0 cutover.
- */
+/** Default 1500 ms delay between SIGTERM and SIGKILL after an abort. */
 const DEFAULT_ESCALATION_MS = 1_500;
 /** Maximum time spent confirming POSIX tree exit after SIGKILL dispatch. */
 const POST_KILL_QUIESCENCE_MS = 500;
@@ -199,11 +182,8 @@ export async function runCliPrompt(opts) {
                 continue;
             }
             if (outcome.unknownRecord !== undefined) {
-                // H3 forward-compat: a stream-json line with a role we don't model
-                // (a future kimi-code role). Log it for diagnostics but keep it OUT of
-                // records[] and out of onRecord — consumers iterate records[] expecting
-                // assistant/tool only. Tolerated, not treated as malformed/error —
-                // EXCEPT that on a native-v2 plan nothing may precede the marker.
+                // Unknown roles are diagnostic-only and excluded from consumer records;
+                // native-v2 still refuses any output before its marker.
                 if (requireMarkerBeforeOutput(`an unknown-role (${outcome.unknownRecord.role}) record`)) {
                     return;
                 }
@@ -216,9 +196,7 @@ export async function runCliPrompt(opts) {
             if (outcome.goalSummary !== undefined) {
                 if (requireMarkerBeforeOutput("goal.summary"))
                     return;
-                // Goal-mode summary is out-of-band metadata for our wrapper, not a
-                // consumer-facing record. First-announce wins (a run emits exactly one,
-                // at session end); capture and skip so records[] stays assistant/tool.
+                // Out-of-band metadata; first-announce-wins, excluded from consumer records.
                 if (announcedGoalSummary === undefined) {
                     announcedGoalSummary = outcome.goalSummary;
                     appendLogLine({
@@ -327,7 +305,7 @@ export async function runCliPrompt(opts) {
         args,
         command_label: opts.commandLabel ?? null,
     });
-    return await new Promise((resolve, reject) => {
+    return await new Promise(async (resolve, reject) => {
         let aborted = false;
         let cancellationTeardown;
         let settlementStarted = false;
@@ -552,21 +530,22 @@ export async function runCliPrompt(opts) {
             });
         };
         opts.signal?.addEventListener("abort", onAbort, { once: true });
-        // Re-check `aborted` AFTER attaching the listener. `await mkdir` above
-        // is the first synchronous yield point after the pre-spawn aborted
-        // check — if abort fired during that await, the signal is already in
-        // an aborted state by the time we reach addEventListener, which does
-        // NOT re-fire for already-aborted signals (per the AbortSignal spec).
-        // Without this re-check the spawned child is orphaned: SIGTERM/SIGKILL
-        // is never sent and the process keeps holding the SQLite row + model
-        // tokens. Audit report 28 (Codex H1) tracked this fix.
+        // Abort may occur during any pre-spawn await, and addEventListener does not
+        // replay an already-aborted signal. Re-check after attaching the listener so
+        // the spawned child cannot escape cancellation teardown.
         if (opts.signal?.aborted === true) {
             onAbort();
         }
-        // Swap the pre-attached early listener for the real handler. These two
-        // statements are synchronous and execute as one unit; no event can
-        // interleave between marking earlyErrorHandled and attaching the new
-        // listener.
+        if (child.pid !== undefined && opts.onSpawn) {
+            try {
+                await opts.onSpawn(child.pid);
+            }
+            catch (error) {
+                onAbort();
+                settle("reject", new RuntimeError("CLI_SPAWN_CALLBACK_FAILED", `Failed to record the spawned kimi process: ${formatError(error)}`, "cli-client.spawn", error instanceof Error ? { cause: error, details: errorDetails() } : { details: errorDetails() }));
+                return;
+            }
+        }
         earlyErrorHandled = true;
         child.on("error", (err) => {
             appendLogLine({ event: "process_error", message: formatError(err) });
@@ -614,7 +593,7 @@ export async function runCliPrompt(opts) {
             await raceWithTimeout(logChain, LOG_DRAIN_TIMEOUT_MS);
             settle("resolve", {
                 spawnedAt,
-                settledAt: 0, // Filled at settlement, after the teardown barrier.
+                settledAt: 0,
                 sessionId,
                 goalSummary: announcedGoalSummary,
                 cliError: announcedCliError,
@@ -722,14 +701,6 @@ export class ResponseTimeoutError extends RuntimeError {
  *
  *   The generic `withTimeout` (runtime/kimi-timeouts.ts) only rejects
  *   the outer Promise — it has no handle on the kimi child process.
- *   review/ask/review-gate previously wrapped `runCliPrompt` with
- *   `withTimeout` and let the orphaned subprocess keep running until
- *   it crashed or finished on its own. The reviewers (reports 17 +
- *   18) flagged this as critical for review_gate in particular: the
- *   8 s budget fires inside Claude Code's Stop hook, the parent
- *   returns "allow stop", and a runaway kimi keeps holding the
- *   SQLite row + model tokens. Subsequent `/kimi:cancel` can't reach
- *   it because `kimi_pid` is null.
  *
  * Behavior:
  *
@@ -811,11 +782,6 @@ function buildArgs(opts) {
             args.push("--skills-dir", dir);
         }
     }
-    // NOTE: thinking effort is requested through the env binding, never CLI argv.
-    // Non-trait-driven providers or a base level already off ignore it silently;
-    // an alwaysThinking model receives off unnormalized. stream-json carries no
-    // thinking deltas (writeThinkingDelta() {} in the JSON writer), so the plugin
-    // cannot observe whether the request was honoured.
     // -p accepts the prompt as the option value. We pass it as a separate argv
     // entry so prompts with leading dashes or whitespace are not interpreted as
     // additional flags.
@@ -826,15 +792,12 @@ function buildEnv(opts) {
     const env = { ...opts.env };
     if (opts.thinkingEffort !== undefined)
         env.KIMI_MODEL_THINKING_EFFORT = opts.thinkingEffort;
-    // 2.2.0 audit: ambient trust starts project MCP stdio servers outside PreToolUse.
+    // Ambient workspace trust starts project MCP stdio servers outside PreToolUse.
     delete env.KIMI_CODE_TRUST_WORKSPACE;
-    // kimi-code 0.33.0 inverted its CLI engine default: an unflagged `kimi -p`
-    // now selects native agent-core-v2, while this upstream-documented flag pins
-    // the legacy-v1 path. Native v2 still has a final-allow plan-file path that
-    // can skip our later external PreToolUse hook, so the engine choice must be a
-    // plugin-owned spawn invariant rather than ambient operator state. Older
-    // kimi-code releases ignore the unknown flag. Always overwrite ambient false
-    // values; accepting one would silently reopen v2 on 0.33+.
+    // Legacy-v1 plans use this flag on releases whose unflagged -p default can
+    // route to native-v2. Always overwrite ambient false values; older releases
+    // ignore it. The engine choice stays plugin-owned, while certified native-v2
+    // plans use the no-plan construction rather than a legacy pin.
     if (opts.executionPlan.intendedEngine === "legacy-v1") {
         env[KIMI_LEGACY_ENV] = KIMI_LEGACY_FORCED_VALUE;
     }
@@ -850,8 +813,6 @@ function buildEnv(opts) {
         env.KIMI_PLUGIN_CC_CMD = opts.commandLabel;
     }
     if (opts.swarmMaxConcurrency !== undefined) {
-        // kimi-code 0.18.0+ caps AgentSwarm's normal-phase concurrency at this
-        // value; older binaries ignore it. See the field doc on CliClientOptions.
         env.KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY = String(opts.swarmMaxConcurrency);
     }
     if (opts.trustedWorkspaceRoot !== undefined) {