kimi-plugin-cc 2.3.1 → 2.4.1

package/dist/version.js

@@ -4,4 +4,4 @@
 // and AGENTS.md on every release. A future improvement would read this from
 // package.json at build time, but that adds a build-step dependency we
 // don't want yet.
-export const KIMI_PLUGIN_CC_VERSION = "2.3.1";
+export const KIMI_PLUGIN_CC_VERSION = "2.4.1";

package/docs/migration.md

@@ -1,6 +1,6 @@
 # Compatibility and upgrades
 
-For plugin 2.3.1, use Kimi Code CLI 2.3.1. The plugin certifies exact native-v2 versions `0.42.0`, `0.43.0`, `0.43.1`, `2.0.0`, `2.0.1`, `2.0.2`, `2.1.0`, `2.1.1`, `2.2.0`, `2.3.0`, and `2.3.1` for all eight operations. It does not automatically accept later patches or minor releases. The npm distribution adds an installation channel; it does not change this compatibility table.
+Plugin 2.4.1 certifies Kimi Code CLI 2.3.2 for all eight operations, alongside exact native-v2 versions `0.42.0`, `0.43.0`, `0.43.1`, `2.0.0`, `2.0.1`, `2.0.2`, `2.1.0`, `2.1.1`, `2.2.0`, `2.3.0`, and `2.3.1`. Later patches and minor releases are not accepted automatically. The npm distribution adds an installation channel; it does not change this compatibility table.
 
 Explicitly pinned legacy-v1 binaries remain supported within `KIMI_TESTED_MINORS`, through 0.41.x, subject to each operation's minimum version. The [runtime table](../runtime/kimi-engine.ts) is the authority.
 
@@ -8,7 +8,17 @@ Use the [README installation and update steps](../README.md) for Claude Code or
 
 ## Plugin versions and upgrades
 
-Plugin versions advance independently using ordinary SemVer and may deliberately align with a certified CLI release. Plugin 2.3.1 certifies CLI 2.3.1; the runtime table records that mapping. Published versions and tags are never reused. Every upstream patch requires its own certification. The native-v2 no-plan profile, plugin/marketplace IDs and existing job store are preserved.
+Plugin versions advance independently using ordinary SemVer and may deliberately align with a certified CLI release. Plugin 2.4.1 certifies exact CLI 2.3.2; the nearby numbers do not imply version alignment. Published versions and tags are never reused. Every upstream patch requires its own certification. The native-v2 no-plan profile, plugin/marketplace IDs and existing job store are preserved.
+
+## CLI 2.3.2 swarm activation
+
+Upstream 2.3.2 removes model self-activation of `AgentSwarm` in fresh print sessions. On that exact version only, swarm commands and MCP calls use the same `runSwarm` lifecycle:
+
+1. A short-lived `web --no-open --host 127.0.0.1 --port 0 --log-level error` process uses authenticated loopback routes to verify the exact v2 server, choose the explicit or configured default model, create a session, bind the model and auto permission, enable and verify `swarm_mode`, and shut down.
+2. One ordinary `kimi -p -r` prompt runner resumes that session. Its recorded session-id source is `preactivated`, and the returned print session must match it.
+3. A second short-lived web lifecycle disables swarm mode, verifies status and the `swarm_mode.exit` journal record, and shuts down.
+
+Activation is inside the job's finite budget. `runSwarm` solely owns deactivation: normal cleanup uses the remaining budget, while failure recovery has a separate two-second cancellation-aware bound and is never retried. Print/session failures stay primary. The ready token stays in memory and out of logs, and success cannot complete if cleanup fails. Post-mutation identity or process/group uncertainty preserves diagnostics and, for write-swarm, the recovery worktree. Process groups are rechecked after teardown; unknown survivors are unverified and unproven groups are not signalled. Older certified versions still launch swarm directly with `kimi -p`. This narrow lifecycle is not a full RPC transport or a model-driven activation workaround; the managed hook and workspace boundaries still govern every tool call.
 
 After updating the plugin, run Claude Code `/kimi:setup` or Codex `$kimi-setup`
 from that host's active install to re-pin its version-stamped hook path, then

package/docs/registry-releases.md

@@ -6,8 +6,12 @@ remain available. The package has no install scripts and no separate CLI.
 
 ## Publishing status
 
-The current release candidate is plugin **2.3.1**, certifying exact CLI **2.3.1**; publication is pending final repository and CI gates. See the [certification evidence](./upstream-2.3.1-certification.md).
-The previous verified publication was **2.2.2**:
+Plugin **2.4.1** certifies exact CLI **2.3.2** for all eight operations with host-preactivated swarm sessions. Its [certification evidence](./upstream-2.3.2-certification.md) includes the source scan, plan controls, hardened 15-test/115-assertion candidate matrix, and final 19-test/125-assertion production smoke in 296.67 seconds. Independent review is complete: Claude reports no blockers and Codex returned RESOLVED. The final repository gate passed 1,268 tests with zero failures and 16,055 assertions across 78 files, and package validation passed 224 files. CI, tagging, and registry verification are pending; the currently published release remains 2.4.0 until that closeout completes.
+
+Plugin **2.4.0** preserves exact CLI **2.3.1** certification and adds the shared MCP transport. [Release v2.4.0](https://github.com/linxule/kimi-plugin-cc/releases/tag/v2.4.0) is anchored at `9232d1ec98465454d8d9328e439d3f31bfc53e04`; its [CI check](https://github.com/linxule/kimi-plugin-cc/actions/runs/40040084944) and [release-event publishing run](https://github.com/linxule/kimi-plugin-cc/actions/runs/40040442610) passed. The registry tarball has SHA-1 `8243616529aa9f03f26bf4fef68c36d90e2304ae`, contains 222 files, and matches the CI artifact byte-for-byte. A fresh npm install passed isolated setup/check for both hosts.
+The previous verified publication was **2.3.1**:
+[Release v2.3.1](https://github.com/linxule/kimi-plugin-cc/releases/tag/v2.3.1) is anchored at `20011ff0554c611afe0a426b30a68c2473175568`; its [CI check](https://github.com/linxule/kimi-plugin-cc/actions/runs/39977037533) and [release-event publishing run](https://github.com/linxule/kimi-plugin-cc/actions/runs/39977818482) passed. The registry tarball has SHA-1 `e309448480a2ce841b49840cdaeeed37acc6c50b`, contains 196 files, and matches the CI artifact byte-for-byte. See the [certification evidence](./upstream-2.3.1-certification.md).
+Earlier verified publication was **2.2.2**:
 [Release v2.2.2](https://github.com/linxule/kimi-plugin-cc/releases/tag/v2.2.2)
 is anchored at `256e78ff7cbf302fb19e8e523d8e3f943f7cb366`; its
 [CI check](https://github.com/linxule/kimi-plugin-cc/actions/runs/39755724024)
@@ -78,8 +82,9 @@ bun run check:package .tmp/npm
 
 The package check inspects the actual tarball, verifies runtime copies and
 vendored licenses, and installs/checks the safety hook in isolated homes for
-both hosts. It also exercises unsupported-version refusal using a fake CLI.
-It does not invoke a model or read the maintainer's Kimi configuration.
+both hosts. It also exercises unsupported-version refusal using a fake CLI and
+modern MCP discovery plus legacy initialization on both extracted compiled
+distributions. It does not invoke a model or read the maintainer's Kimi configuration.
 
 ## First publication (completed bootstrap reference)
 
@@ -119,8 +124,5 @@ release. `.github/workflows/publish.yml` runs on `release.published`; it checks
 the tag against `package.json`, runs the full gate and package smoke, then
 publishes the validated tarball through OIDC with provenance. The publish job
 has no source checkout or build scripts. A manual dispatch with an existing
-release tag is available for a first OIDC release or recovery after a verified
-publication failure. Check npm before retrying; released versions are immutable.
-
-A locally bootstrapped first version is already published: do not dispatch it
-again. The next release is the first OIDC publication.
+release tag is available for recovery after a verified publication failure.
+Check npm before retrying; released versions are immutable.

package/docs/safety.md

@@ -2,7 +2,7 @@
 
 This guide describes the current checkout runtime. Read-only tasks deny file writes and shell commands. Rescue and pursue can edit your workspace. Write-swarm returns a patch from a temporary Git worktree.
 
-Native agent-core-v2 is certified at exact CLI versions `0.42.0`, `0.43.0`, `0.43.1`, `2.0.0`, `2.0.1`, `2.0.2`, `2.1.0`, `2.1.1`, `2.2.0`, `2.3.0`, and `2.3.1`, with plan mode disabled. The [runtime certification table](../runtime/kimi-engine.ts) controls routing. The hook is not an operating-system sandbox.
+Native agent-core-v2 is certified at exact CLI versions `0.42.0`, `0.43.0`, `0.43.1`, `2.0.0`, `2.0.1`, `2.0.2`, `2.1.0`, `2.1.1`, `2.2.0`, `2.3.0`, `2.3.1`, and `2.3.2`, with plan mode disabled. The [runtime certification table](../runtime/kimi-engine.ts) controls routing. The hook is not an operating-system sandbox.
 
 ## Why the safety story is hook-based
 
@@ -205,12 +205,24 @@ If another installed host still points to an older hook, that hook may veto thes
 - **Resume is intentionally not exposed yet.** In goal mode `goal.summary` emits a *goalId* distinct from the resume-hint *sessionId*; `kimi -r <sessionId>` re-enters the session but not necessarily the goal continuation. The plugin captures and surfaces the goalId but does not offer `--resume` for pursue until that split is reconciled upstream — exposing it now would be a silent-failure trap. **Re-verified against kimi-code 0.26.0 (2026-07-16):** the headless CLI still has no argv, prompt syntax, or session-resume path that calls `resumeGoal()`. `parseHeadlessGoalCreate` (`apps/kimi-code/src/cli/goal-prompt.ts`) accepts only the `/goal <objective>` *create* shape on both the v1 and experimental-v2 drivers, and upstream's own docs (`docs/en/guides/goals.md`, § "Use goal mode carefully") state that in non-interactive prompt mode *only goal creation is supported* — goal management is a TUI/kimi-web control. PR #552 makes a plain `-r <sessionId>` correctly *restore* the paused goal snapshot, but nothing in the headless path *acts* on it; the real `resumeGoal()` is wired only to the TUI (`/goal resume`) and kimi-web RPC (PR #1693, web-only). Implementing `--resume` would therefore require either prompt-injected model compliance (rejected — the plugin bounds autonomy with hard limits, not model goodwill) or abandoning the subprocess model for kimi-web's RPC. Re-check if upstream ever ships a headless `goal resume` verb.
 - **A model-invocable `kimi-pursue` agent (v1.3) wraps this command.** The main thread can dispatch autonomous goal mode, not just the human-typed `/kimi:pursue` — the same command↔agent mirror as rescue/review/swarm. Auto-dispatch does NOT widen the blast radius: pursue runs under `commandLabel: "rescue"`, so the managed PreToolUse hook + workspace allowlist gate every tool call on every continuation turn (no git mutation), and the mandatory `--budget` wall-clock ceiling bounds the autonomy regardless of who launched it. Because it is write-capable AND autonomous — the plugin's highest blast radius — the agent's description requires an explicit user request for hands-off multi-turn pursuit, steers single bounded tasks to `kimi-rescue`, and never auto-promotes a fix or a question into a goal loop. Like the command, it refuses without the hook and offers no `--resume`.
 
+## Swarm activation on CLI 2.3.2
+
+Upstream 2.3.2 removes model self-activation of `AgentSwarm` in fresh print sessions. A rejected call can therefore coexist with zero child journals and a successful exit; a tool-call record, aggregate denial, or coordinator-produced patch does not prove fan-out. The plugin does not use prompt workarounds or replace its print transport with general RPC.
+
+For versions requiring activation (currently exact 2.3.2), both slash-command and MCP swarm operations use the same `runSwarm` implementation and one ordinary `kimi -p -r` prompt runner per job, bracketed by short-lived host-managed web lifecycles:
+
+1. The exact planned CLI starts `web --no-open --host 127.0.0.1 --port 0 --log-level error`. The plugin accepts only the expected loopback ready URL, uses a supplied token for authenticated REST requests, and keeps that token in memory, never writing it to logs. `/api/v1/meta` must confirm backend v2, the exact planned version, and no dangerous authentication bypass. The plugin uses the explicit model or environment-model alias, otherwise reading the default alias from `/api/v1/config`; creates a session in the job cwd; binds that model with `permission_mode:auto` and `swarm_mode:true`; verifies those settings and `plan_mode:false` through `/status`; verifies clean shutdown; and requires the main journal's manual `swarm_mode.enter` record.
+2. The ordinary stream-json print runner resumes that session with `kimi -p -r`. The job records `kimi_session_id_source:"preactivated"`, and the session returned by print must exactly match the preactivated id. Every coordinator and child tool call remains governed by the same managed PreToolUse hook and operation allowlist.
+3. After the print run, a second web lifecycle sets `swarm_mode:false`, verifies `/status`, shuts down cleanly, and requires `swarm_mode.exit` in the main journal. Activation consumes part of the same finite job budget rather than extending it. `runSwarm` solely owns session deactivation: normal cleanup uses the remaining budget, while failure recovery has a separate two-second cancellation-aware bound and is never retried. Print/session failures stay primary, with exit codes and cleanup diagnostics preserved. Cancellation aborts the owned lifecycle and never starts a fresh cleanup server. Every post-mutation failure retains the session identity; process/group uncertainty is marked without inventing an ID; process groups are rechecked after teardown, unknown survivors are unverified, unproven groups are never signalled, and a same-PID/start-token process that changes PGID remains active but is not a validated signal target. Root loss requires a previously observed matching identity; first-missing roots and actual probe errors/timeouts remain unverified. Reparenting and PGID moves preserve the current verified child identity for revalidation rather than treating it as exited. Unverified cleanup prevents success and preserves raw output, structured diagnostics, and the write worktree for recovery.
+
+Older certified versions keep the direct `kimi -p` path. The web processes are narrow, planned lifecycle helpers, not a second model runner and not a general RPC transport.
+
 ## Read-only swarm (`/kimi:swarm`)
 
 `/kimi:swarm` (v1.2) fans a **read-only** review out across subagents using kimi-code's `AgentSwarm` tool (kimi-code 0.12.0+). The coordinator launches one subagent per target (file/module/question); each inspects the workspace with read tools and reports findings, which the coordinator consolidates into one markdown report. It opens **zero new write surface**.
 
 - **The hook label is `swarm`, and it allows the read-only tool set PLUS `AgentSwarm`.** The coordinator must be allowed to call `AgentSwarm` (else the swarm never launches), but no write/edit/shell tool is allowed. The exact allowed tool name is `AgentSwarm` (verified at 0.42.0 against `packages/agent-core-v2/src/features/swarm/tools/agent-swarm/agentSwarmTool.ts`: `'AgentSwarm'`, strict schema). The singular `Agent` tool is deliberately *not* allowed — swarm is the fan-out surface, not arbitrary delegation.
-- **Every subagent inherits the `swarm` label and fires the same hook.** On native v2 (0.42.0) `AgentSwarm` children run in-process in a child DI scope with their OWN eager external-hooks service, so every child tool call passes the same before-execute channel and the same managed hook — there is no sub-vs-main branch and no deny-all shortcut on the swarm route. So a subagent's `Write`/`Edit`/`Bash` is denied exactly like a single-turn review's. The swarm listener in that channel is non-terminal and nothing auto-approves `AgentSwarm` ahead of the hook. (Legacy-v1 ≤ 0.41 reached the same result by placing the hook policy at index 0 of every agent's permission stack.) **This is locked by a real-binary smoke** (`tests/runtime/real-binary-smoke.test.ts`, run via `bun run smoke:real`): it spawns the real binary under the `swarm` label with an adversarial prompt that forces a spawned subagent to attempt a write, and asserts that **no file lands** and the hook deny marker appears — converting the subagent-denial claim from source-read-verified to runtime-test-verified.
+- **Every subagent inherits the `swarm` label and fires the same hook.** On native v2 (0.42.0) `AgentSwarm` children run in-process in a child DI scope with their OWN eager external-hooks service, so every child tool call passes the same before-execute channel and the same managed hook — there is no sub-vs-main branch and no deny-all shortcut on the swarm route. So a subagent's `Write`/`Edit`/`Bash` is denied exactly like a single-turn review's. The swarm listener in that channel is non-terminal and nothing auto-approves `AgentSwarm` ahead of the hook. (Legacy-v1 ≤ 0.41 reached the same result by placing the hook policy at index 0 of every agent's permission stack.) **Required for final certification evidence** (`tests/runtime/real-binary-smoke.test.ts`, run via `bun run smoke:real`): distinct child journals must exist, and each assigned Write/Edit `path` must be correlated through its `toolCallId` with the managed denial in that exact tool result; unrelated denials and coordinator-only reports are insufficient. On 2.3.2, targeted controls also prove that direct OFF produces no children while the preactivated ON path produces the real child journals and denials.
 - **The managed hook is the read-only boundary; no `explore`-profile second layer is assumed.** Production deliberately omits `subagent_type` for read-only swarm rather than selecting kimi-code's `explore` profile. Every coordinator and subagent tool call is enforced by the same managed hook.
 - **Swarm refuses without the hook, like every model-spawning command.** A swarm makes the reason especially acute: it asks for up to `--cap` subagents, but this total-count hint is advisory, so a missing hook would remove enforcement from all of them at once. `KIMI_PLUGIN_CC_SKIP_HOOK_CHECK=1` remains an explicit tests/diagnostics escape hatch, not a recovery path.
 - **The only new risk is COST, and the plugin bounds it.** Read-only swarm writes nothing, so the new risk is runaway cost from N parallel model runs (and possible nested `AgentSwarm`). `/kimi:swarm` enforces a **mandatory finite wall-clock ceiling** via its AbortController (`--budget`, default 30m); the SIGTERM→SIGKILL descendant-reaping cancellation reaps the whole subagent process tree. Two **distinct** subagent bounds: `--cap N` is a *soft* prompt-injected hint on TOTAL subagent count (the hook is stateless and cannot enforce a count, so the model may exceed it), and `--max-concurrency N` is a *hard* ceiling on how many subagents kimi-code's `SubagentBatch` runs concurrently — exported as `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` (PR #888) on **kimi-code 0.18.0+** (older binaries ignore the unknown env var, so on < 0.18 only the soft hint applies). It **defaults to 4** when the user passes none (`resolveSwarmMaxConcurrency` in swarm.ts), so every swarm run — agent-dispatched or human-typed — carries an enforced peak-parallelism ceiling on 0.18.0+ rather than falling back to kimi-code's internal ramp; pass an explicit value to widen or throttle. **Never merge them into one flag:** concurrency ≠ total count — a hard concurrency cap of N still permits more than N subagents over the life of the run, just never more than N at once. The `--budget` bounds elapsed time, not a dollar amount or total token count; `--max-concurrency` bounds *peak* parallelism (the spike in simultaneous model spend), and `--cap` is only an advisory total-count nudge. Folding both onto one flag would create the "cap-as-total-count illusion" — a user reading `--cap N` would expect a total bound but receive only a peak-parallelism one.
@@ -226,9 +238,23 @@ If another installed host still points to an older hook, that hook may veto thes
 - **The plugin never touches git; the main thread owns the merge.** Subagents cannot run git (allowlist denies mutation). The plugin captures the change set with `git add -N` (intent-to-add, so new files appear in the diff WITHOUT writing loose objects into the shared object DB) + `git diff --binary` (untruncated, applyable), writes it to a `swarm-write-<jobId>.patch` artifact, and prints the path. It does **not** `git apply`, commit, or move any ref — the user/main thread reviews the patch and applies it (`git apply <path>`). The worktree shares the main repo's object DB and refs, but no ref/HEAD is ever moved, so the user's repository state is untouched.
 - **The patch is captured on every terminal path, before cleanup.** Success, cancel, budget-expiry, and failure all capture the (possibly partial) patch BEFORE `git worktree remove --force` discards the tree, so a cancelled run never silently loses the work the subagents already did. If capture itself fails, the job fails instead of completing and the worktree is retained with its path in the error details for recovery. That guarantee covers the plugin's own terminal paths, including `companion.sh cancel`. It does **not** cover a harness interrupt: Esc/TaskStop delivers SIGTERM then SIGKILL after ~1.35s (measured, process-group-wide), which is shorter than the 1500ms child escalation plus quiescence plus patch capture — so a hard interrupt can kill the companion mid-teardown and lose the patch. `companion.sh cancel` signals from a separate process not racing that deadline and is the work-preserving stop. A startup sweep reaps worktrees orphaned by a hard kill (SIGKILL of the plugin process); its reap TTL is derived as `MAX_DURATION_MS + 2h` so it always exceeds the longest a run can live (the 24h `--budget` cap) and can never force-remove a still-live worktree out from under a concurrent run — the sweep's only liveness signal is the worktree dir mtime, which a run editing only existing files leaves frozen at `git worktree add` time.
 - **Gated tightly.** Requires kimi-code **≥ 0.18.0** (below it `KIMI_CODE_AGENT_SWARM_MAX_CONCURRENCY` is ignored, so a write fan-out would have no hard peak bound — unacceptable for concurrent writers); because that cap cannot be guaranteed without a confirmed version, the write-mode version gate **fails closed** on an unconfirmable `kimi --version` probe (the shared execution-plan gate also refuses unverified or uncertified binaries for read-only swarm; older certified legacy versions may lack the hard concurrency setting). Also requires a git repo with a **committed HEAD**, and the PreToolUse hook (**refuses** without it, like read swarm). Bases the worktree on HEAD, so a **loud warning** fires when the working tree is dirty (uncommitted work is not visible to the swarm). Default `--max-concurrency` is **1** (serialize) since disjoint-target partitioning is prompt-only and unenforceable by the stateless hook; the coordinator prompt also forbids git mutation and nested `AgentSwarm`.
-- **Field-proven by a real-binary smoke.** `tests/runtime/real-binary-smoke.test.ts` runs the real `runSwarm --write` and asserts the POSITIVE end-to-end (a `coder` subagent's edits land in the worktree, captured as a patch; the user's real tree is byte-identical + git-clean; the worktree is cleaned up) plus the NEGATIVE (an absolute-path write outside the trusted root is hook-denied). It is the check that catches `tool_input` field-name drift — `Write`/`Edit` carry `path`, not `file_path`, and reading the wrong key denies every real write silently.
+- **Required for final certification evidence.** `tests/runtime/real-binary-smoke.test.ts` runs the real `runSwarm --write` and requires the POSITIVE end-to-end: distinct child journals contain their assigned edits with `Write`/`Replaced` results on the same `toolCallId`, those child-authored changes land in the worktree and captured patch, the user's real tree is byte-identical + git-clean, and the worktree is cleaned up. A patch without per-call child provenance is not accepted as fan-out evidence. The NEGATIVE lane correlates each absolute out-of-root `path` and `toolCallId` with its managed denial. It is the check that catches `tool_input` field-name drift — `Write`/`Edit` carry `path`, not `file_path`, and reading the wrong key denies every real write silently.
 - **Model-invocable agent (v1.5), patch-only by construction.** Following the field-proof above, `--write` now has a `kimi-swarm-write` subagent so the main thread can dispatch a write fan-out on its own judgement — the same human-command + model-invocable-agent split the rest of the suite uses. Auto-dispatch is a safe extension here because it widens **no** write surface and removes **no** bound: the agent path runs the identical `runSwarm --write` code, so edits still land only in the throwaway worktree, the managed hook still gates every `coder` subagent, the patch is still handed back for the user to apply (**the plugin never applies or commits**), and `--budget` + default `--max-concurrency` 1 + the hook requirement all still hold. In fact write-swarm is a *less* dangerous agent than the `kimi-pursue` agent already shipped: pursue writes directly into the workspace, whereas write-swarm's output is a patch the human reviews before anything reaches a real tree. Because it is still a write surface, the agent description demands BOTH signals — many disjoint write targets AND explicit fan-out intent — and steers single edits to `kimi-rescue`, read-only fan-outs to `kimi-swarm`, and autonomous loops to `kimi-pursue`. Default `--max-concurrency` stays **1**; raising it (concurrent writers) remains a deliberate, human-or-explicitly-requested choice.
 
+## MCP transport and long-running jobs
+
+The plugin also bundles an MCP stdio server for Claude Code and Codex. This is an additive transport, not a second execution engine or a way around the managed hook. The seven model tools run the same certified companion operations, exact-version checks, native-v2 preflight, workspace allowlists, finite budgets, and artifact rendering as the slash commands and skills. The review gate remains a separate Stop-hook feature.
+
+Claude Code task-capable calls return durable MCP task IDs and use `tasks/get` and `tasks/cancel`. Codex currently consumes ordinary MCP tool results, not this task extension: after attachment, model tools return a job handle when the job is still running or its terminal result when already settled. `kimi_job_status`, `kimi_job_result`, and `kimi_job_cancel` provide polling and cancellation. Do not describe the Codex path as native MCP tasks.
+
+Claude supplies its project directory as the default workspace. A configured host workspace is a containment boundary: an explicit workspace must be that directory or a descendant, not an arbitrary override. Codex calls normally supply an absolute `workspace` on the initial operation because its packaged stdio server runs from the plugin root; that explicit path is the operation's trust choice. Subsequent job control can use the persisted binding. Job controls manage only MCP-launched jobs, require the same canonical workspace and repository, and cannot inspect or cancel an arbitrary CLI job by ID.
+
+Attachment waits for the operation to install cancellation handlers, with a 60-second bound. Verified teardown can close a stalled launch; missing identity or inconclusive termination evidence keeps it starting and recoverable by ID. `kimi_pid` is recorded at actual spawn rather than inferred from a later process-list match.
+
+The MCP task/job ID is preassigned and bound to the job's real `operation_kind`, not merely its lineage. `mcp_tasks` stores launch and ownership metadata; the normal `jobs` table remains the outcome authority. Failed jobs, including budget timeouts, produce completed tasks with `isError:true` and the failed-job artifact, so partial output is not mistaken for a final answer. Supervisor and protocol failures are distinct from ordinary Kimi failures.
+
+Closing an MCP connection does not cancel work. A later server reopens the same store and resumes status/result handling by ID. Generic stale sweeps skip MCP-owned rows, and direct CLI cancellation refuses them; use MCP job controls for those jobs. Companion and observed Kimi-descendant identities include start tokens and process groups; MCP cancellation and stale cleanup revalidate them rather than signalling a recycled PID. Cancellation remains cooperative and does not roll back edits. Pursue teardown and write-swarm patch capture still run through the existing companion path; write-swarm captures its patch on every terminal path before removing the worktree.
+
 ## Response budgets and partial output (2.2.0)
 
 Every single-turn command runs under a wall-clock budget: ask, review and
@@ -265,9 +291,9 @@ at it (the runtime resolves that path instead of `kimi` on `PATH`; every spawn
 still exports `KIMI_CODE_NO_AUTO_UPDATE=1`, so the pinned copy never drifts).
 
 ```sh
-PIN=~/.local/share/kimi-plugin-cc/kimi-bin/2.2.0
+PIN=~/.local/share/kimi-plugin-cc/kimi-bin/2.3.2
 mkdir -p "$PIN" && cd "$PIN" && printf '{"name":"kimi-plugin-cc-pin","private":true}\n' > package.json
-bun add @moonshot-ai/kimi-code@2.2.0
+bun add @moonshot-ai/kimi-code@2.3.2
 export KIMI_PLUGIN_CC_KIMI_BIN="$PIN/node_modules/.bin/kimi"   # e.g. in ~/.zshenv
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kimi-plugin-cc",
-  "version": "2.3.1",
-  "description": "Kimi for Claude Code and Codex: code questions, independent reviews, bounded fixes, autonomous goals, and parallel tasks through the local Kimi Code CLI.",
+  "version": "2.4.1",
+  "description": "Kimi for Claude Code and Codex: code questions, independent reviews, bounded fixes, autonomous goals, parallel tasks, and MCP tools through the local Kimi Code CLI.",
   "type": "module",
   "engines": {
     "node": ">=22.5.0"
@@ -13,7 +13,7 @@
     "build": "rm -rf dist && bunx tsc -p tsconfig.build.json && mkdir -p dist/vendor/shell-quote dist/vendor/smol-toml && cp runtime/vendor/shell-quote/LICENSE dist/vendor/shell-quote/LICENSE && cp runtime/vendor/smol-toml/*.js runtime/vendor/smol-toml/LICENSE dist/vendor/smol-toml/ && echo '{\"type\":\"module\"}' > dist/package.json",
     "companion": "node --import tsx runtime/companion.ts",
     "test": "bun test",
-    "smoke:real": "KIMI_PLUGIN_CC_SMOKE=1 bun test tests/runtime/real-binary-smoke.test.ts",
+    "smoke:real": "KIMI_PLUGIN_CC_SMOKE=1 bun test tests/runtime/real-binary-smoke.test.ts --path-ignore-patterns '**/worktrees/**'",
     "check:package": "node scripts/check-package.mjs"
   },
   "devDependencies": {
@@ -38,14 +38,18 @@
     "claude-code",
     "codex",
     "kimi",
+    "kimi-code",
     "plugin",
-    "code-review"
+    "code-review",
+    "mcp",
+    "model-context-protocol"
   ],
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"
   },
   "files": [
+    ".mcp.json",
     ".claude-plugin/",
     ".agents/plugins/marketplace.json",
     "agents/",

package/plugins/kimi-codex/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "kimi",
-  "version": "2.3.1",
-  "description": "Kimi for Codex: code questions, independent reviews, bounded fixes, autonomous goals, and parallel tasks through the local Kimi Code CLI.",
+  "version": "2.4.1",
+  "description": "Kimi for Codex: code questions, independent reviews, bounded fixes, autonomous goals, parallel tasks, and MCP job controls through the local Kimi Code CLI.",
   "author": {
     "name": "linxule"
   },
@@ -14,13 +14,16 @@
     "review",
     "code-review",
     "delegation",
-    "multi-model"
+    "multi-model",
+    "mcp",
+    "model-context-protocol"
   ],
   "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
   "interface": {
     "displayName": "Kimi",
     "shortDescription": "Ask, review, and build with Kimi",
-    "longDescription": "Kimi Code workflows for Codex: read-only explanations and reviews, bounded workspace fixes, autonomous goals, and parallel tasks. Codex skills call a self-contained shell runtime; no MCP server is required.",
+    "longDescription": "Kimi Code workflows for Codex: read-only explanations and reviews, bounded workspace fixes, autonomous goals, and parallel tasks. Codex skills call a self-contained shell runtime, with MCP tools provided by the bundled server.",
     "developerName": "linxule",
     "category": "Developer Tools",
     "capabilities": [

package/plugins/kimi-codex/.mcp.json

@@ -0,0 +1,28 @@
+{
+  "mcpServers": {
+    "kimi": {
+      "type": "stdio",
+      "command": "./scripts/companion.sh",
+      "args": [
+        "mcp"
+      ],
+      "cwd": ".",
+      "env_vars": [
+        "KIMI_PLUGIN_CC_DATA",
+        "CLAUDE_PLUGIN_DATA",
+        "PLUGIN_DATA",
+        "KIMI_CODE_HOME",
+        "KIMI_PLUGIN_CC_KIMI_BIN",
+        "KIMI_PLUGIN_CC_KIMI_PREFIX_ARGS",
+        "KIMI_PLUGIN_CC_NODE_BIN",
+        "KIMI_PLUGIN_CC_HOOK_SCRIPT",
+        "KIMI_PLUGIN_CC_HOST_ID",
+        "KIMI_MODEL_NAME",
+        "KIMI_MODEL_API_KEY",
+        "KIMI_MODEL_PROVIDER_TYPE",
+        "KIMI_MODEL_BASE_URL",
+        "KIMI_MODEL_THINKING_EFFORT"
+      ]
+    }
+  }
+}

package/plugins/kimi-codex/dist/cli-client.js

@@ -60,7 +60,7 @@ export async function runCliPrompt(opts) {
         });
     }
     const args = buildArgs(opts);
-    const env = buildEnv(opts);
+    const env = buildKimiCliEnvironment(opts);
     if (opts.logPath !== undefined) {
         await mkdir(path.dirname(opts.logPath), { recursive: true }).catch(() => {
             // Best-effort; if mkdir fails the appendFile below will error and be
@@ -305,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;
@@ -536,6 +536,16 @@ export async function runCliPrompt(opts) {
         if (opts.signal?.aborted === true) {
             onAbort();
         }
+        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) });
@@ -778,7 +788,7 @@ function buildArgs(opts) {
     args.push("-p", opts.prompt);
     return args;
 }
-function buildEnv(opts) {
+export function buildKimiCliEnvironment(opts) {
     const env = { ...opts.env };
     if (opts.thinkingEffort !== undefined)
         env.KIMI_MODEL_THINKING_EFFORT = opts.thinkingEffort;

package/plugins/kimi-codex/dist/commands/ask.js

@@ -1,5 +1,5 @@
 import { companionHelp } from "../help.js";
-import { randomUUID } from "node:crypto";
+import { allocateJobId } from "../job-id.js";
 import path from "node:path";
 import { createCliCancellationHandlers } from "../cli-cancellation.js";
 import { runCliPromptWithBudget } from "../cli-client.js";
@@ -55,7 +55,7 @@ export async function runAsk(argv, context) {
     const store = new JobStore(paths);
     try {
         await sweepStaleJobs(store, paths);
-        const jobId = randomUUID();
+        const jobId = allocateJobId(context);
         const sessionResolution = await resolveAskSession(store, repoIdentity.repoId, parsed.fresh, parsed.resume, parsed.resumeTarget);
         const askPrompt = buildAskPrompt(parsed.prompt, sessionResolution.reusedSession);
         const executionPlan = await prepareKimiExecutionPlan({
@@ -152,6 +152,7 @@ export async function executeAskJob(jobId, prompt, context, options) {
         }
         handlers = createCliCancellationHandlers();
         const executionPlan = executionPlanFromPersisted(job);
+        store.updateRunningJob(job.job_id, { phase: "turn-running" });
         // Re-validate resume lineage from the store before spawning: a detached
         // worker (or a forged queued row) reloads the persisted plan and would
         // otherwise hand kimi_session_id to the spawn without the dispatch-time
@@ -174,6 +175,7 @@ export async function executeAskJob(jobId, prompt, context, options) {
             thinkingEffort: job.thinking_effort ?? undefined,
             resumeSessionId: job.kimi_session_id ?? undefined,
             logPath: job.stream_log_path,
+            onSpawn: (pid) => { store.updateRunningJob(job.job_id, { kimi_pid: pid }); },
             signal: handlers.signal,
         }, job.budget_ms ?? KIMI_ASK_PROMPT_TIMEOUT_MS, "ask.prompt");
         store.updateRunningJob(job.job_id, observedExecutionFields(result));

package/plugins/kimi-codex/dist/commands/cancel.js

@@ -5,6 +5,7 @@ import { markJobCancelled, sweepStaleJobs } from "../jobs.js";
 import { JobStore, withJobStore } from "../job-store.js";
 import { ensurePluginPaths, resolvePluginPaths } from "../paths.js";
 import { parseJobLookupArgs } from "../parsing.js";
+import { revalidateProcessIdentities } from "../process-tree.js";
 import { getManagedCommandConfig } from "./registry.js";
 export async function runCancel(argv, context) {
     const parsed = parseJobLookupArgs(argv);
@@ -31,6 +32,10 @@ export async function runCancel(argv, context) {
                 message: "cancel is a no-op for terminal jobs.",
             }, null, 2)}\n`;
         }
+        if (store.getMcpTask(job.job_id) &&
+            (context.mcpCompanionIdentity === undefined || context.mcpKimiIdentity === undefined)) {
+            throw new RuntimeError("MCP_CANCEL_REQUIRES_BINDING", `MCP job ${job.job_id} requires MCP job-control cancellation with recorded identities; use tasks/cancel or kimi_job_cancel.`, "mcp.cancel");
+        }
         if (job.pid === null && job.kimi_pid === null) {
             throw new RuntimeError("CANCEL_NOT_SUPPORTED", `Job ${job.job_id} does not have a recorded process id to cancel.`, "cancel.runtime");
         }
@@ -53,6 +58,7 @@ export async function runCancel(argv, context) {
             catch (error) {
                 preMarkError = error;
             }
+            await assertMcpCompanionIdentity(job, context.mcpCompanionIdentity);
             signalJobProcesses(job, "SIGTERM");
             await sleep(1_000);
             if (hasLiveRecordedProcess(job)) {
@@ -67,6 +73,8 @@ export async function runCancel(argv, context) {
                 message: "review_gate cancelled; SIGTERM→SIGKILL escalation completed.",
             }, null, 2)}\n`;
         }
+        await assertMcpCompanionIdentity(job, context.mcpCompanionIdentity);
+        await assertMcpKimiIdentity(job, context.mcpKimiIdentity);
         signalJobProcesses(job, "SIGTERM");
         const cancelled = await waitForCancellation(paths, job.job_id);
         if (cancelled) {
@@ -76,7 +84,11 @@ export async function runCancel(argv, context) {
                 message: "Cancellation completed.",
             }, null, 2)}\n`;
         }
-        signalJobProcesses(job, "SIGKILL");
+        const companionMatches = await assertMcpCompanionIdentity(job, context.mcpCompanionIdentity, true);
+        const kimiMatches = await assertMcpKimiIdentity(job, context.mcpKimiIdentity, true);
+        if (companionMatches || kimiMatches) {
+            signalJobProcesses(job, "SIGKILL", { companion: companionMatches, kimi: kimiMatches });
+        }
         await withJobStore(paths, async (forcedStore) => {
             const current = forcedStore.getJob(job.job_id);
             if (current?.status === "running") {
@@ -93,11 +105,38 @@ export async function runCancel(argv, context) {
         store.close();
     }
 }
-function signalJobProcesses(job, signal) {
+async function assertMcpCompanionIdentity(job, expected, allowMissing = false) {
+    return assertMcpProcessIdentity(job.pid, expected, "companion", allowMissing);
+}
+async function assertMcpKimiIdentity(job, expected, allowMissing = false) {
+    return assertMcpProcessIdentity(job.kimi_pid, expected, "Kimi", allowMissing);
+}
+async function assertMcpProcessIdentity(actualPid, expected, label, allowMissing) {
+    if (expected === undefined)
+        return true;
+    if (expected === null) {
+        if (actualPid === null)
+            return false;
+        throw new RuntimeError("CANCEL_NOT_SUPPORTED", `MCP job ${actualPid} has no verified ${label} identity; refusing PID-only cancellation.`, "mcp.cancel");
+    }
+    if (actualPid !== expected.pid) {
+        throw new RuntimeError("MCP_PROCESS_IDENTITY_MISMATCH", `The recorded ${label} process identity no longer matches; no signal was sent.`, "mcp.cancel");
+    }
+    const validation = await revalidateProcessIdentities([expected]);
+    if (!validation.complete) {
+        throw new RuntimeError("MCP_PROCESS_IDENTITY_UNAVAILABLE", `The ${label} identity probe was inconclusive; no further signal was sent and the job was not changed.`, "mcp.cancel");
+    }
+    const matches = validation.identities.length > 0;
+    if (!matches && !allowMissing) {
+        throw new RuntimeError("MCP_PROCESS_IDENTITY_MISMATCH", `The recorded ${label} process identity no longer matches; no signal was sent.`, "mcp.cancel");
+    }
+    return matches;
+}
+function signalJobProcesses(job, signal, include = { companion: true, kimi: true }) {
     const pids = new Set();
-    if (job.pid !== null)
+    if (include.companion && job.pid !== null)
         pids.add(job.pid);
-    if (job.kimi_pid !== null)
+    if (include.kimi && job.kimi_pid !== null)
         pids.add(job.kimi_pid);
     for (const pid of pids) {
         try {

package/plugins/kimi-codex/dist/commands/cli-helpers.js

@@ -117,7 +117,11 @@ export async function captureTimeoutPartialOutput(classified, store, job, env, c
         return undefined;
     const result = timeout.partialResult;
     let sessionId = result.sessionId;
-    let source = sessionId ? "announced" : null;
+    let source = sessionId
+        ? sessionId === job.kimi_session_id
+            ? job.kimi_session_id_source
+            : "announced"
+        : null;
     const details = classified instanceof RuntimeError ? classified.details : timeout.details;
     details.kimi_session_id_source = job.kimi_session_id_source;
     // The persisted plan is plugin-owned. Recovery never runs on cancellation,

package/plugins/kimi-codex/dist/commands/pursue.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { allocateJobId } from "../job-id.js";
 import path from "node:path";
 import { createCliCancellationHandlers } from "../cli-cancellation.js";
 import { runCliPromptWithBudget } from "../cli-client.js";
@@ -122,7 +122,7 @@ export async function runPursue(argv, context) {
             env: context.env,
         });
         const prompt = buildGoalPrompt(objective, parsed.turns);
-        const jobId = randomUUID();
+        const jobId = allocateJobId(context);
         const logPath = path.join(paths.logsDir, `pursue-${jobId}.jsonl`);
         const job = store.createJob({
             job_id: jobId,
@@ -226,6 +226,7 @@ async function executePursueJob(jobId, prompt, objective, budgetMs, context) {
             model: job.model ?? undefined,
             thinkingEffort: job.thinking_effort ?? undefined,
             logPath: job.stream_log_path,
+            onSpawn: (pid) => { store.updateRunningJob(job.job_id, { kimi_pid: pid }); },
             signal: handlers.signal,
         }, budgetMs, "pursue.prompt");
         store.updateRunningJob(job.job_id, observedExecutionFields(result));

package/plugins/kimi-codex/dist/commands/rescue.js

@@ -1,5 +1,5 @@
 import { companionHelp } from "../help.js";
-import { randomUUID } from "node:crypto";
+import { allocateJobId } from "../job-id.js";
 import path from "node:path";
 import { createCliCancellationHandlers } from "../cli-cancellation.js";
 import { runCliPromptWithBudget } from "../cli-client.js";
@@ -61,7 +61,7 @@ export async function runRescue(argv, context) {
             resumeSessionId: sessionResolution.kimiSessionId ?? undefined,
             resumeSource: sessionResolution.sourceJob,
         });
-        const jobId = randomUUID();
+        const jobId = allocateJobId(context);
         const logPath = path.join(paths.logsDir, `rescue-${jobId}.jsonl`);
         const job = store.createJob({
             job_id: jobId,
@@ -192,6 +192,7 @@ export async function executeRescueJob(jobId, prompt, context, options) {
             thinkingEffort: job.thinking_effort ?? undefined,
             resumeSessionId: job.kimi_session_id ?? undefined,
             logPath: job.stream_log_path,
+            onSpawn: (pid) => { store.updateRunningJob(job.job_id, { kimi_pid: pid }); },
             signal: handlers.signal,
         }, job.budget_ms ?? KIMI_RESCUE_PROMPT_TIMEOUT_MS, "rescue.prompt");
         store.updateRunningJob(job.job_id, observedExecutionFields(result));

package/plugins/kimi-codex/dist/commands/review-gate.js

@@ -166,10 +166,7 @@ async function executeReviewGate(payload, assistantMessage, context) {
         try {
             const activeStore = store;
             // runCliPromptWithBudget ties the 8 s timeout to an AbortController
-            // that kills the kimi child on expiry — review_gate runs inside
-            // Claude Code's Stop hook, so a runaway kimi after timeout would
-            // hold model tokens with no way for /kimi:cancel to reach it
-            // (the SQLite row's kimi_pid is null). See reports/17 and 18.
+            // that kills the kimi child on expiry and records its PID at spawn.
             const result = await runCliPromptWithBudget({
                 cwd: payload.cwd,
                 env: context.env,
@@ -182,6 +179,7 @@ async function executeReviewGate(payload, assistantMessage, context) {
                 // Requested via env; provider/model may ignore it. The 8s budget still applies.
                 thinkingEffort,
                 logPath,
+                onSpawn: (pid) => { activeStore.updateRunningJob(job.job_id, { kimi_pid: pid }); },
             }, KIMI_REVIEW_GATE_TIMEOUT_MS, "review_gate.runtime");
             activeStore.updateRunningJob(job.job_id, observedExecutionFields(result));
             assertCliResultSuccess(result, "review_gate.runtime");

package/plugins/kimi-codex/dist/commands/review.js

@@ -1,4 +1,4 @@
-import { randomUUID } from "node:crypto";
+import { allocateJobId } from "../job-id.js";
 import path from "node:path";
 import process from "node:process";
 import { createCliCancellationHandlers } from "../cli-cancellation.js";
@@ -38,7 +38,7 @@ export async function runReview(argv, context, commandType) {
         env: context.env,
     });
     const store = new JobStore(paths);
-    const jobId = randomUUID();
+    const jobId = allocateJobId(context);
     // Leave kimi_session_id NULL until kimi announces an actual ID; never invent
     // one that no on-disk session matches.
     const reviewSessionId = null;
@@ -75,6 +75,7 @@ export async function runReview(argv, context, commandType) {
     const reviewConfig = getManagedCommandConfig(commandType);
     const cancel = reviewConfig.cancellation;
     const handlers = createCliCancellationHandlers();
+    store.updateRunningJob(job.job_id, { phase: "turn-running" });
     try {
         const result = await runCliPromptWithBudget({
             cwd: context.cwd,
@@ -87,6 +88,7 @@ export async function runReview(argv, context, commandType) {
             model: parsed.model,
             thinkingEffort: parsed.thinkingEffort,
             logPath,
+            onSpawn: (pid) => { store.updateRunningJob(job.job_id, { kimi_pid: pid }); },
             signal: handlers.signal,
         }, job.budget_ms ?? KIMI_REVIEW_PROMPT_TIMEOUT_MS, `${commandType}.prompt`);
         store.updateRunningJob(job.job_id, observedExecutionFields(result));