kimi-plugin-cc 2.0.7

package/docs/migration.md

@@ -0,0 +1,215 @@
+# Compatibility and upgrades
+
+For plugin 2.0.3, use Kimi Code CLI 2.0.1. The plugin also certifies exact native-v2 versions `0.42.0`, `0.43.0`, `0.43.1`, and `2.0.0` for all eight operations. It does not automatically accept later patches or minor releases.
+
+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.
+
+Use the [README installation and update steps](../README.md) for Claude Code or Codex. Model and provider choices are covered in the [model setup guide](./models.md). Do not change your host application's authentication to configure Kimi.
+
+## Plugin versions and upgrades
+
+Plugin versions advance independently using ordinary SemVer. Plugin 2.0.3 certifies
+exact Kimi Code CLI 2.0.1; the runtime table records that mapping. Each compatible
+maintenance or certification update takes the next unused plugin patch. 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.
+
+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
+run setup with `--check`. This fixes path drift, not policy omissions in an older installed plugin. Older coexisting hooks still veto pursue goal-status tools; update each host only when authorized. Keep `default_plan_mode` absent or false. Upgrades
+from pre-1.10 releases must also follow the historical native-v2 migration section below.
+
+## Historical migration instructions
+
+<details>
+<summary>Earlier migrations from the Python CLI and legacy engine</summary>
+
+These sections record earlier upgrades. Old tags, paths, and installation commands are historical examples, not the current installation procedure. Follow the current guidance above for the current release.
+
+## Migrating from v0.4 to v1.0
+
+v1.0 of kimi-plugin-cc targets the **kimi-code** Node.js binary (Moonshot's successor to Kimi CLI). The v0.4.x line targeted the Python **Kimi CLI** over its Wire JSON-RPC transport. kimi-code dropped the Wire transport from its first release, so v1.0 is a hard cut rather than a backwards-compatible upgrade.
+
+If you're already running v0.4.x with the Python Kimi CLI, you have a choice:
+
+- **Stay on v0.4** if you depend on `kimi --wire`. The [`v0.4.0`](https://github.com/linxule/kimi-plugin-cc/releases/tag/v0.4.0) tag is the stable reference point; a `v0.4-maintenance` branch is cut from that tag for ongoing fixes (once published, pin to it via `linxule/kimi-plugin-cc@v0.4-maintenance`).
+- **Upgrade to v1.0** if you've installed (or are willing to install) kimi-code. v1.0 gets the new safety story (PreToolUse hook), kimi-code's vis-server integration for free, and a leaner subprocess transport.
+
+## What changes between v0.4 and v1.0
+
+| | v0.4 | v1.0 |
+|---|---|---|
+| Backing CLI | Python [Kimi CLI](https://github.com/MoonshotAI/kimi-cli) | [kimi-code](https://kimi.com/code/docs) (Node.js) |
+| Transport | `kimi --wire` (JSON-RPC over stdio) | `kimi -p --output-format stream-json` (subprocess + NDJSON) |
+| Per-command safety | YAML agent profiles (`exclude_tools`) shipped in the plugin | PreToolUse hook installed in `~/.kimi-code/config.toml` |
+| Session id | Client-assigned UUID, passed via `--session` | Server-minted, captured from kimi's stream-json `session.resume_hint` record (stderr announce fallback) |
+| Web UI integration | `kimi web` + PATCH `/api/sessions/{id}` for pre-run human-readable titles | Shared Desktop/Web session store, repaired prompt previews and replaceable fallback titles for native-v2 sessions |
+| Replay log format | Wire JSON-RPC events (`{direction, message}`) | cli-client NDJSON (`{event, record}`) |
+| Marketplace name | `kimi-marketplace` (plugin: `kimi`) — unchanged | same `kimi-marketplace` / `kimi` (v1 upgrades in place) |
+| Rescue allowlist | In-band approval policy on the Wire client | Out-of-band via the PreToolUse hook (same allowlist code) |
+
+The marketplace + plugin IDs are unchanged from v0.4, so an existing install can update in place — but only after kimi-code is installed locally. Without kimi-code the new transport has nothing to spawn, so the order matters: install kimi-code first, then update the plugin.
+
+## Upgrade procedure
+
+### 1. Install kimi-code
+
+Follow Moonshot's install steps at [kimi.com/code/docs](https://kimi.com/code/docs). Verify it works on its own:
+
+```
+kimi --version
+kimi -p "Reply READY"
+```
+
+### 2. Audit your kimi-plugin-cc env block
+
+If you set any of these env vars for v0.4, review them before continuing — v1.0 reads the same vars but with different effective semantics:
+
+| Env var | Notes |
+|---|---|
+| `KIMI_PLUGIN_CC_KIMI_BIN` | Path to the kimi binary. Was the Python `kimi` in v0.4; should now point at the kimi-code binary (typically `~/.kimi-code/bin/kimi`). Unset to use the kimi-code on `PATH`. |
+| `KIMI_PLUGIN_CC_KIMI_PREFIX_ARGS` | JSON array of args prepended to every kimi spawn. Was a Wire-mode flag carrier in v0.4; in v1 it's still honored but the v0.4 contents (`--wire`, `--session`, `--agent-file`) are gone. Unset unless you have a specific override reason. |
+| `KIMI_PLUGIN_CC_NODE_BIN` | Absolute path to the Node binary used to run the companion AND the hook script. v1 setup hard-requires absolute. |
+| `KIMI_PLUGIN_CC_HOOK_SCRIPT` | Override for the hook script path written into `~/.kimi-code/config.toml`. Tests / advanced users only. |
+| `KIMI_CODE_HOME` | Override for the kimi-code config directory (default `~/.kimi-code`). New in v1.0 — recognized by setup, install verifier, and the hook itself. |
+| `KIMI_PLUGIN_CC_SKIP_HOOK_CHECK` | Bypasses every hook-verification refusal gate (and the review-gate skip), restoring un-enforced `permission: auto` execution. Only set for tests or deliberate diagnostics. |
+| `CLAUDE_PLUGIN_DATA` | Plugin data root. Unchanged from v0.4. |
+
+### 3. Update the plugin in place
+
+From an existing v0.4 install:
+
+```
+/plugin marketplace update linxule
+# then in the /plugin UI: select kimi → "Update now"
+```
+
+Or fresh install on a machine that doesn't have v0.4:
+
+```
+/plugin marketplace add linxule/kimi-plugin-cc
+/plugin install kimi@kimi-marketplace
+```
+
+(v0.4 ALPHA NOTE: v1.0.0-alpha.1 was briefly tagged with renamed IDs `kimi-v1` / `kimi-marketplace-v1`. The rename was rolled back in v1.0.0-alpha.2. If you happened to install alpha.1 by those names, uninstall first: `/plugin uninstall kimi-v1`, `/plugin marketplace remove kimi-marketplace-v1`, then follow the procedure above.)
+
+### 4. Run setup
+
+```
+/kimi:setup
+```
+
+This writes the PreToolUse hook to `~/.kimi-code/config.toml` and runs a two-layer probe (direct + via `/bin/sh -c`) to verify the hook fires and denies as expected. If setup fails, look at the `Probe:` line in the output. Common failure codes (the runtime emits these as `SETUP_*` errors):
+
+- **Bad `KIMI_PLUGIN_CC_NODE_BIN` override** — v1 setup requires the override to be an absolute path; relative paths (`node`) are rejected with `SETUP_NODE_BIN_NOT_ABSOLUTE`.
+- **Orphan markers in `~/.kimi-code/config.toml`** from a manual edit or aborted earlier setup. Run `/kimi:setup --uninstall` to clean up, then `/kimi:setup` again. Code: `SETUP_ORPHAN_MARKERS`.
+- **Duplicate managed blocks** from two setup runs racing. Same fix: `/kimi:setup --uninstall` + `/kimi:setup`. Code: `SETUP_DUPLICATE_BLOCKS`.
+- **Hook script path contains characters TOML can't represent** (quotes, control chars). Reinstall to a path without these, or set `KIMI_PLUGIN_CC_HOOK_SCRIPT` to a safe path. Code: `SETUP_HOOK_PATH_UNSAFE`.
+- **Probe timed out** (5s budget). Usually means kimi-code or the Node binary is wedged on cold start. Re-run; if persistent, file an issue with `/kimi:setup --check` output.
+- **Hook script not found** — `dist/hooks/approval-hook.js` is missing. Reinstall the plugin or run `bun run build` if you're on a local clone. Code: `SETUP_HOOK_SCRIPT_MISSING`.
+
+### 5. Verify
+
+```
+/kimi:setup --check
+```
+
+Reports the install state without writing. Run `/kimi:review` against a small diff to confirm the round-trip works end-to-end.
+
+### Local-clone install upgrade
+
+If you're running the plugin via `claude --plugin-dir ~/kimi-plugin-cc` rather than the marketplace:
+
+```bash
+cd ~/kimi-plugin-cc
+git fetch --tags origin
+git checkout v1.0.0-alpha.2
+# Verify dist/ is in sync; if you previously deleted it locally, rebuild:
+ls dist/hooks/approval-hook.js >/dev/null || bun run build
+# Restart Claude Code so the new agents/ and dist/ register
+```
+
+Then run `/kimi:setup` in your Claude Code session. The local clone uses the same managed-block installer; no marketplace operations needed.
+
+### Using both Claude Code and Codex (v1.7.0+)
+
+Claude Code and Codex install the plugin to **different, version-stamped paths**
+but share one `~/.kimi-code/config.toml`. As of **v1.7.0** each host manages its
+**own** host-scoped PreToolUse block (`# === BEGIN kimi-plugin-cc-managed:claude-code …`
+vs `:codex`), so:
+
+- Run **`/kimi:setup` in Claude Code AND `$kimi-setup` in Codex** — once each.
+  They no longer clobber each other; both blocks coexist and each host verifies
+  its own. (Before v1.7.0 a single shared block was overwritten every time you
+  switched hosts, which is why setup seemed to "need redoing.")
+- **One-time cleanup on upgrade to v1.7.0:** update the plugin in *both* hosts,
+  then run setup in each. The first setup adopts your old un-suffixed block and
+  prunes orphaned hook entries left by earlier installs.
+- `/kimi:setup --uninstall` removes only the current host's block. Use
+  `/kimi:setup --uninstall --all` to remove *every* host's block from the shared
+  config (a deliberate full nuke — it clears blocks for **all** hosts, not just
+  this one).
+
+> **⚠️ Upgrade both hosts before re-running setup.** During the window where one
+> host is on v1.7.0+ and the other is still on ≤1.6.5, running setup on the OLD
+> host writes an un-suffixed block that can overwrite the block the new host just
+> migrated, re-creating the clobber (or leaving a duplicate the new host rejects
+> with `SETUP_DUPLICATE_BLOCKS`). Update **both** Claude Code and Codex to v1.7.0+
+> first, then run setup in each. If the config ever looks tangled, the clean-slate
+> escape hatch is `/kimi:setup --uninstall --all` followed by setup in each host.
+
+## Data and session continuity
+
+- **SQLite job rows** from v0.4 remain in `${CLAUDE_PLUGIN_DATA}/kimi-plugin-cc/state.db`. They're still visible to `/kimi:status` and `/kimi:result`, but `/kimi:replay` will report `REPLAY_LOG_UNREADABLE` on the v0.4 wire logs — v1.0's replay parser doesn't understand the Wire JSON-RPC shape. Archive or delete the database if you don't need v0.4 history.
+- **Kimi CLI sessions** under `~/.kimi/sessions/` are independent of kimi-code's `~/.kimi-code/sessions/`. v1.0's `--resume` will not see v0.4 sessions.
+- **Plugin config** (`${CLAUDE_PLUGIN_DATA}/kimi-plugin-cc/config.json` — only `reviewGateEnabled` lives here) carries over unchanged.
+
+## Rollback
+
+If something is wrong, the v0.4 install is one step away:
+
+```
+/kimi:setup --uninstall            # removes the v1.0 PreToolUse hook
+/plugin uninstall kimi
+/plugin marketplace remove kimi-marketplace
+# If the v0.4-maintenance branch is published:
+/plugin marketplace add linxule/kimi-plugin-cc@v0.4-maintenance
+# Otherwise, pin to the v0.4.0 tag:
+/plugin marketplace add linxule/kimi-plugin-cc@v0.4.0
+/plugin install kimi@kimi-marketplace
+```
+
+Claude Code's marketplace tooling uses `@ref` to pin a GitHub shorthand to a branch or tag. Your Python Kimi CLI install is untouched — v1.0 only edits `~/.kimi-code/config.toml`, never `~/.kimi/*`.
+
+## What's gone
+
+- The `--wire`, `--session`, and `--agent-file` invocation shape. v1.0 uses `kimi -p` only.
+- The YAML agent profiles in `runtime/agents/`. The plugin doesn't ship Kimi-side profiles in v1.0; per-command safety is enforced exclusively by the PreToolUse hook.
+- The Wire-protocol replay path. The runtime no longer parses JSON-RPC turn events.
+- The v0.4 pre-run `Kimi Task: ...` title assignment path through Kimi CLI / `kimi web`. v1 uses `kimi -p`, whose session id is minted only after the run, so the plugin cannot name the session before spawn. Instead, after Kimi announces the session id and the run settles, the runtime syncs a fallback title such as `Kimi Ask: ...`, repairs missing native-v2 prompt previews, and notifies the Desktop/Web index. Native-v2 fallback titles remain eligible for native generation; manual and already-generated titles are preserved. Internal `review_gate` Stop-hook sessions are intentionally excluded. See [session visibility and native titles](session-visibility.md) for generation limits and repair of older plugin sessions.
+
+## What's new
+
+- A two-layer setup probe that catches `node`-not-on-PATH failure modes before they become silent fail-opens.
+- Workspace-bound rescue safety enforced by a hook that the plugin sets `KIMI_PLUGIN_CC_CMD=rescue` for. The hook only enforces the allowlist when that env var is set — kimi-code invocations from outside the plugin (e.g., direct user `kimi -p` calls) keep kimi-code's default permission posture, unrestricted by the plugin. The allowlist's job is to scope plugin-driven rescue, not to police all uses of kimi-code on the system.
+- `/kimi:setup --check` and `/kimi:setup --uninstall` for state inspection and cleanup.
+- Stream-json logs are easier to grep than Wire JSON-RPC dumps when you need to debug a job after the fact.
+
+If you hit problems, file an issue with the output of `/kimi:setup --check` and the contents of the managed block in `~/.kimi-code/config.toml` (the block is between the BEGIN and END markers — don't paste the rest of your kimi-code config).
+
+## Upgrading to 1.10 (native agent-core-v2, kimi-code 0.42.0)
+
+This release changes behaviour that earlier 1.x users may depend on. Strictly by semver it is a major; it ships as 1.10.0 because the plugin is upgraded in place through the marketplace and its 1.x line has always advanced compat by minor releases.
+
+- **Certification is now per EXACT kimi-code version, not per minor.** Native v2 is certified at `0.42.0` only (v1.10.0; v1.10.3 adds `0.43.0` and `0.43.1`). When kimi-code publishes a newer version, every model-spawning command refuses with `KIMI_CAPABILITY_NOT_CERTIFIED` until a plugin release certifies it — before 1.10, a patch release inside a tested minor kept working. kimi-code self-upgrades in the background, so expect this on the next upstream patch; pin `KIMI_PLUGIN_CC_KIMI_BIN` to a certified binary if you need continuity, and watch for the next plugin release.
+- **Sessions created before 1.10 cannot be resumed on 0.42.0.** `ask --resume`, `ask -r`, `rescue --resume` and rescue's implicit latest-session reuse refuse (`KIMI_SESSION_LINEAGE_UNKNOWN` / `KIMI_SESSION_ENGINE_MISMATCH`) — the v1 engine no longer exists in the binary, so nothing could replay those sessions. Nothing is deleted; `/kimi:status`, `/kimi:result` and `/kimi:replay` still work on the old jobs. Start fresh sessions.
+- **`default_plan_mode = true` (any spelling) in `~/.kimi-code/config.toml` now blocks every command** (`CLI_V2_PLAN_MODE_CONFIGURED`). On the old forced-v1 path that setting was harmless; on native v2 it would arm the one code path that bypasses the safety hook. Set it to `false` or remove it. `/kimi:setup` cannot fix this one.
+- **`KIMI_PLUGIN_CC_KIMI_PREFIX_ARGS` may no longer contain kimi flags** (`-r`, `-c`/`-C`, `-S`, `-p`, `-m`, `--plan`, `--yolo`, `--agent`, `--add-dir`, …) — `INVALID_ENV`. The prefix is a launcher shim only (e.g. `["--import","tsx",…]`).
+- **`[experimental] tower` / `subagent_fork` and `KIMI_CODE_EXPERIMENTAL_FLAG` refuse before spawn** (`CLI_V2_EXPERIMENTAL_UNSAFE` / `CLI_V2_HOOK_ORDER_UNSAFE`). Unset them for plugin-managed runs.
+- **Still on kimi-code ≤ 0.41.x?** Nothing changes for you: those versions route to the legacy-v1 engine exactly as before. But the plugin certifies them only for an explicitly pinned binary — kimi-code's auto-update will move you to 0.42.x, at which point the notes above apply.
+
+No action for the job store (one additive nullable column, migrated automatically) or the hook policy (unchanged allowlists). As with every release, run `/kimi:setup` (or `$kimi-setup`) after updating so the hook is re-pinned to the new install path — a `kimi login` also strips the managed-block markers, and setup restores them.
+
+None of these refusals is repaired by `/kimi:setup`; all of them carry `retryable_after_setup: false` explicitly from 1.10.1 (an absent field must still be treated as `false`). They are catalogued with remedies in [docs/safety.md § Refusal codes](./safety.md#refusal-codes-of-the-native-v2-contract-v1100).
+
+</details>

package/docs/models.md

@@ -0,0 +1,82 @@
+# Models and provider setup
+
+The plugin uses your configured Kimi model by default. You can ask for a different
+configured model for one task without changing that default.
+
+## See configured models
+
+In Claude Code, run `/kimi:setup --models`. In Codex, ask `$kimi-setup` to list
+models. The underlying command is:
+
+```sh
+"<plugin-root>/scripts/companion.sh" setup --models
+"<plugin-root>/scripts/companion.sh" setup --models --json
+```
+
+This lists local model aliases, provider IDs/types, the saved default, and any
+`KIMI_MODEL_NAME` default overlay inherited by the companion. It also reports
+whether secondary-model settings exist. It does not contact providers, read the
+OAuth store, write configuration, or test authentication. Configured entries
+are not a guarantee of working credentials, model access, or tool support.
+Provider catalogs refreshed by Kimi may add models not yet present locally.
+
+## Choose a model for a task
+
+Say “review this with my configured fast model” or pass its exact alias:
+
+```text
+/kimi:review -m 'my-provider/my-model' review this diff
+/kimi:ask -m 'my-provider/my-model' explain the cache
+```
+
+The Claude agents and Codex skills list models when you request a model in
+natural language. They select a unique configured match, ask when there are
+several, and guide setup when there is none. They do not guess model IDs or
+silently substitute the default after an error. An explicit `-m` remains a
+pass-through alias, so upstream can resolve it or report an error.
+
+Omitting `-m` uses the default for a **fresh** session. A resumed session keeps
+its previous model unless you supply `-m`. The optional review gate also uses
+the default unless `KIMI_PLUGIN_CC_REVIEW_GATE_MODEL` explicitly selects an alias.
+Swarm `-m` selects the coordinator; upstream `[secondary_model]` settings can
+select different models for its children.
+
+## Add a provider or change the saved default
+
+Open native `kimi` using the same `KIMI_CODE_HOME` as the plugin:
+
+1. For a Kimi subscription, use `/login`.
+2. For an API key or another provider, use `/provider` and follow its native
+   prompts. Enter credentials there, never in the host conversation. Provider
+   setup may offer a default-model picker; select a new saved default only if
+   you want that persistent change.
+3. To explicitly change your saved default later, use native `/model`.
+4. Return to the plugin, list models again, then run `setup --check` to verify
+   hook readiness. If it requests re-pinning, run the host's setup command.
+
+Kimi supports its managed account, Anthropic, OpenAI-compatible services,
+OpenAI Responses, Google GenAI, and Vertex AI protocols. Available models and
+authentication requirements depend on the provider. See the upstream
+[provider setup guide](https://www.kimi.com/code/docs/en/kimi-code-cli/configuration/providers).
+The plugin does not switch Claude Code or Codex's own authentication.
+
+For a one-off connection test, explicitly request a small task with the chosen
+alias. That makes a provider call under your account and the usual plugin
+safety gates. Listing alone is offline. An authentication or unsupported-model
+error is surfaced without retrying a different model.
+
+## Implementation boundary
+
+`setup --models [--json]` is mutually exclusive with hook setup flags. It parses
+the complete TOML in memory and emits an explicit field allowlist; it never
+serializes providers, keys, headers, environment maps, endpoints, OAuth
+references, or raw parse errors. Do not substitute `kimi provider list --json`:
+upstream 2.0.0 includes credential-bearing provider objects in that output.
+Names in the inventory are untrusted configuration data and must be passed as
+one correctly shell-quoted argument, never evaluated as shell instructions.
+
+The model list is a routing aid, not a second implementation of Kimi's config
+validator. Every task still uses the existing exact-version, hook, workspace,
+and no-plan checks. Source review is against kimi-code 2.0.0 (`1b89e4b0`),
+including `kosongConfig/configSection.ts`, `envOverlay.ts`, and
+`cli/v2/run-v2-print.ts`.

package/docs/registry-releases.md

@@ -0,0 +1,70 @@
+# Registry releases
+
+The npm package `kimi-plugin-cc` ships the Claude plugin at its root and the
+self-contained Codex plugin under `plugins/kimi-codex`. GitHub marketplaces
+remain available. The package has no install scripts and no separate CLI.
+
+## Validation
+
+Use the repository's normal version bump and generated-surface procedure in
+AGENTS.md. Keep plugin and npm versions identical. Certification for new Kimi
+Code versions still requires the source audit and real-binary controls; adding
+a registry channel does not certify another CLI version.
+
+```sh
+bun install --frozen-lockfile
+bun run build
+bun run generate:surfaces
+# Review and stage generated distributions before the drift gate.
+bun run check
+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.
+
+## First publication
+
+The package must first exist on npm before its package settings can be configured.
+After the release commit passes CI, create its immutable version tag and GitHub
+release using the normal AGENTS.md procedure. The workflow builds and uploads a
+validated tarball; publishing stays disabled until the repository variable
+`NPM_TRUSTED_PUBLISHING` is `true`. Download the `npm-package` workflow artifact,
+authenticate to npm interactively, then publish that validated artifact:
+
+```sh
+npm login
+npm publish kimi-plugin-cc-X.Y.Z.tgz --access public
+```
+
+Do not publish a placeholder or reuse a version. Inspect registry metadata and
+install the published version into a temporary directory before announcing it.
+
+Configure npm Trusted Publishing for this package:
+
+- GitHub owner: `linxule`
+- Repository: `kimi-plugin-cc`
+- Workflow: `publish.yml`
+- Environment: `npm`
+- Allow direct publishing for this release workflow
+
+After configuring trust, set the GitHub Actions repository variable
+`NPM_TRUSTED_PUBLISHING=true` to enable future publications.
+
+No npm token is stored in GitHub. The npm CLI is used only for registry
+operations; Bun remains the development toolchain.
+
+## Subsequent releases
+
+Push the reviewed release commit, wait for CI, tag it, and publish its GitHub
+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.