oppnc · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026 · Jul 30, 2026
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
@@ -6,13 +6,13 @@
   },
   "metadata": {
     "description": "Claude Code / Grok plugins that run local Kimi Code as a coding subagent over ACP.",
-    "version": "0.1.1"
+    "version": "0.2.0"
   },
   "plugins": [
     {
       "name": "kimi",
-      "description": "Kimi Code subagent via ACP — multimodal, goals, session resume, frontend-first.",
-      "version": "0.1.1",
+      "description": "REQUIRED frontend/UI handoff to local Kimi Code via ACP; main agent must not implement UI when ready (happy path: /kimi:rescue).",
+      "version": "0.2.0",
       "author": {
         "name": "oppnc",
         "url": "https://github.com/oppnc"

diff --git a/.gitignore b/.gitignore
@@ -36,3 +36,6 @@ coverage/
 # Claude / Grok local overrides
 .claude/settings.local.json
 .grok/
+
+# Local test sandbox (manual Kimi frontend testing)
+_behavior_sandbox/
diff --git a/AGENTS.md b/AGENTS.md
@@ -17,7 +17,7 @@ Marketplace id: `kimi-code-cc` · plugin id: `kimi` → install as `kimi@kimi-co
 
 Sibling package for Codex: `kimi-plugin-codex` (different plugin format).
 
-## Version (keep in sync — all **0.1.1**)
+## Version (keep in sync — all **0.2.0**)
 
 | Location | Field |
 | --- | --- |
@@ -79,7 +79,7 @@ node plugins/kimi/scripts/kimi-companion.mjs task --resume -- \
   "Continue from where you left off"
 ```
 
-Optional env: `KIMI_CLI_PATH`, `KIMI_PLUGIN_CC_DATA_DIR`, `CLAUDE_SESSION_ID` / `GROK_SESSION_ID`.
+Optional env: `KIMI_CLI_PATH`, `KIMI_PLUGIN_CC_DATA_DIR`, `CLAUDE_SESSION_ID` / `GROK_SESSION_ID`, `KIMI_BRIDGE_HANDOFF=1` (legacy host handoff bullets; default off), `KIMI_FORCE_CONTINUE=0` (disable Mode B incomplete-work continue nudges; default on).
 
 ### Companion commands
 
@@ -93,12 +93,14 @@ Optional env: `KIMI_CLI_PATH`, `KIMI_PLUGIN_CC_DATA_DIR`, `CLAUDE_SESSION_ID` /
 
 ## How host agents should call Kimi
 
-1. **Substantial** implementation / UI / multimodal / multi-file → Agent `kimi:kimi-rescue` (see `/kimi:rescue`). Do **not** call `Skill(kimi:kimi-rescue)` or re-enter the slash from a forked agent.
-2. **Light** one-shot → `kimi-companion.mjs task` (or `/kimi:task`).
+1. **REQUIRED** for any frontend/UI (including style mocks, reference pages, prototypes, “try a look”), CSS/layout/components, screenshot/video visual bugs, multimodal debugging, multi-file coding → Agent `kimi:kimi-rescue` (see `/kimi:rescue`). Main agent **MUST NOT** write/edit those UI files itself. Do **not** call `Skill(kimi:kimi-rescue)` or re-enter the slash from a forked agent.
+2. **Light** non-UI one-shot only → `kimi-companion.mjs task` (or `/kimi:task`).
 3. One companion invocation; return **stdout verbatim**. No invented system prompts or review rubrics.
 4. Prefer `--image` / `--video` / `--media` for screenshots and recordings over describing pixels in prose.
 5. Default `--mode yolo` unless the user asked for plan/auto/default.
-6. Preserve `--resume` / `--fresh` / `--session` / `--goal` / `--git` / `--model` / `--thinking` / `--background`.
+6. Preserve `--resume` / `--fresh` / `--session` / `--goal` / `--git` / `--model` / `--thinking` / `--background` / `--json`.
+7. Soft “prefer” is not enough: treat handoff as **mandatory** whenever the task touches UI surfaces and Kimi is available (after `/kimi:setup` / companion setup ok).
+8. **Empty / failed handoff:** exit ≠ 0, `(no agent text)`, or JSON `ok:false` / `emptyAgentText:true` → re-dispatch **once** (`--fresh`), still **no** main-thread UI coding. See rescue / `kimi-cli-runtime` acceptance tables.
 
 Skill contract: `plugins/kimi/skills/kimi-cli-runtime/SKILL.md`.
 
@@ -112,6 +114,22 @@ There is no human answering Kimi permission prompts; the companion answers them.
 | `default` | Auto-approve tool requests (prefer session-level allow) |
 | `plan` | Approve read-oriented tools; reject mutating tools; **decline** `ExitPlanMode` (`plan_reject_and_exit`) so plan mode delivers a plan and does **not** start execution |
 
+### Turn acceptance (Mode A / Mode B — keep isomorphic with kimi-plugin-codex)
+
+Shared policy lives in `scripts/lib/turn-policy.mjs` and is applied inside `runKimiAcpTurn`:
+
+| Mode | Symptom | Companion action |
+| --- | --- | --- |
+| **A — empty** | `end_turn` with no agent text and no tools | Up to **2** fresh-session retries, then **1** same-session empty-recovery nudge (`emptyAgentText` / `emptyRetried` / `emptyRecoveryNudged`). Still empty → job **`failed`**, **exit code 1** |
+| **B — incomplete** | Disk/action task ends after plan text or only read/search tools (no Write/Edit/Bash) | Up to **2** **same-session** continue nudges (`incompleteContinued` / `continueCount` / `incompleteReason`); stagnates if no progress |
+
+- **B is off** in `plan` mode (plan text is the deliverable).
+- **B is off** for Q&A / how-to (`What is…`, `How do I implement…`), pure **reply-exactly** probes, and completion-claim text without tools.
+- **B is on** for EN/CJK disk-action verbs, goals, file-path cues; not bare `ui`/`css` tokens alone.
+- Disable B globally: `KIMI_FORCE_CONTINUE=0`.
+- Pure empty turns are **not** reclassified as B; Mode A owns them.
+- Claude-style `message.result` reassembly does **not** apply — Kimi empty turns have no recoverable result body (peer empty detection + retry + fail-loud only).
+
 ### Timeouts (agent-controlled)
 
 - **Default: no ACP request deadline** for `task` / `goal` / background jobs. Kimi may run until it finishes, fails, or is cancelled.
@@ -133,7 +151,8 @@ There is no human answering Kimi permission prompts; the companion answers them.
 - Host session binding via `CLAUDE_SESSION_ID` / `GROK_SESSION_ID` is **best-effort**; missing id → most recent job in current workspace.
 - Foreground failures are recorded as failed jobs (visible via `status` / `result`).
 - **Orphan recovery:** `status` / `result` / `--wait` call `reconcileStaleJobs()` — `running` jobs whose runner PID is dead are rewritten to `failed` with `orphaned: true` (no more infinite fake "running").
-- Background runners heartbeat `updatedAt` / `toolEventCount` every ~10s; prefer **foreground** rescue unless the user asks to detach.
+- **Job phases:** `queued` → `launching` → `starting_acp` → `running` → terminal; `lastProgressMessage` surfaces tool/agent progress on status.
+- Background runners heartbeat `updatedAt` / `toolEventCount` / phase every ~10s; prefer **foreground** rescue unless the user asks to detach.
 
 ## Platform notes
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,7 +2,33 @@
 
 **Language / 语言:** [English](CHANGELOG.md) | [中文](CHANGELOG.zh-CN.md)
 
-## Unreleased
+## 0.2.0
+
+Public package version continues from GitHub **0.1.x** as **0.2.0** (aligned with **kimi-plugin-codex** 0.2.0).
+
+### Added
+- Job **phase** + **lastProgressMessage** on background jobs (queued → launching → starting_acp → running → terminal)
+- Richer status render: phase, progress, resume hint; status list preview 50 + phase padEnd 18
+- `lib/prompt.mjs` + `tests/prompt.test.mjs`; optional `KIMI_BRIDGE_HANDOFF=1` bridge notes (default off)
+
+### Changed
+- Core companion alignment with **kimi-plugin-codex** 0.2.0 (shared progress / prompt stack)
+- Harder host triggers: agent/command/skill copy uses **REQUIRED / MUST / MUST NOT** for frontend/UI (including style mocks and reference pages); main agent must not implement UI when Kimi is ready
+- Host command shells **functionally similar** to Codex skills: routing tables (UI → rescue), flag lists, long-run status/result notes, setup nextSteps (Claude/Grok/CLI), Fix: `/kimi:sessions`
+- Version **0.2.0** (aligned with sibling Codex package)
+
+## 0.1.2
+
+### Added
+- **First verify** path in README + setup `nextSteps` (hand a small frontend task to Kimi)
+- Setup doctor: Node version, workspace source, soft Kimi Code **compat** notes, actionable `errorCode`
+- Standardized `[kimi-plugin]` errors with numbered **Fix** lists (`lib/errors.mjs`)
+- Workspace root resolution from host env (`CLAUDE_PROJECT_DIR`, `GROK_WORKSPACE`, `KIMI_WORKSPACE`, …)
+- Media path resolve against workspace cwd + clearer not-found errors (agent-facing)
+
+### Changed
+- Happy path only in user docs: `/kimi:rescue` for frontend/UI/screenshot/video; advanced details stay in AGENTS.md
+- Stronger host triggers for frontend / visual / video handoff (`kimi-rescue`, setup, rescue command)
 
 ## 0.1.1
 

diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md
@@ -2,7 +2,33 @@
 
 **Language / 语言:** [English](CHANGELOG.md) | [中文](CHANGELOG.zh-CN.md)
 
-## 未发布 (Unreleased)
+## 0.2.0
+
+公开包版本自 GitHub **0.1.x** 起记为 **0.2.0**（与 **kimi-plugin-codex** 0.2.0 锁步）。
+
+### 新增
+- 后台 job 的 **phase** + **lastProgressMessage**（queued → launching → starting_acp → running → 终态）
+- 更丰富的 status 渲染：phase、progress、resume 提示；列表 preview 50 + phase padEnd 18
+- `lib/prompt.mjs` + `tests/prompt.test.mjs`；可选 `KIMI_BRIDGE_HANDOFF=1`（默认关闭）
+
+### 变更
+- companion 核心与 **kimi-plugin-codex** 0.2.0 对齐（共享 progress / prompt 栈）
+- 加强宿主触发语气：agent/命令/skill 文案对前端/UI（含风格稿、参考页）使用 **REQUIRED / MUST / MUST NOT**；Kimi 可用时主 agent 不得自己写 UI
+- 宿主 command 薄壳与 Codex skills **功能类似**（路由表、flag、long-run 轮询、Fix 文案）
+- 版本 **0.2.0**（与 Codex 兄弟包对齐）
+
+## 0.1.2
+
+### 新增
+- README + setup 的 **首次验证**（把一个小前端任务交给 Kimi）
+- Setup doctor：Node 版本、workspace 来源、Kimi Code **compat** 软检查、可行动 `errorCode`
+- 标准化 `[kimi-plugin]` 错误与 **Fix** 列表（`lib/errors.mjs`）
+- 从宿主环境解析工作区根目录
+- 媒体路径相对 workspace 解析 + 更清晰的缺失错误
+
+### 变更
+- 用户文档只保留主路径：`/kimi:rescue`；高级细节见 AGENTS.md
+- 加强前端 / 截图 / 视频 触发描述
 
 ## 0.1.1
 

diff --git a/README.md b/README.md
@@ -4,90 +4,115 @@
 
 [![CI](https://github.com/oppnc/kimi-plugin-cc/actions/workflows/ci.yml/badge.svg)](https://github.com/oppnc/kimi-plugin-cc/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
-[![Version](https://img.shields.io/badge/version-0.1.1-green.svg)](./CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.2.0-green.svg)](./CHANGELOG.md)
 
-This plugin does one thing: call **[Kimi Code](https://github.com/MoonshotAI/kimi-code)** as a subagent.
+Call local **[Kimi Code](https://github.com/MoonshotAI/kimi-code)** as a subagent from **Claude Code** or **Grok**.
 
-Kimi k3 is strong at frontend and multimodal work. In its familiar environment (Kimi Code), it is even stronger. If you prefer not to live in the Kimi CLI, want to boost your main agent’s frontend ability, or want to spend limited Kimi tokens where they count — this is for you.
-
-Thin ACP bridge only. No reimplemented system prompts. Tools, swarm, skills, and models stay with Kimi Code.
+Kimi k3 is strong at frontend and multimodal work — and stronger inside Kimi Code. This plugin is a **thin ACP bridge**: tools, swarm, skills, and models stay with Kimi Code.
 
 | | |
 | --- | --- |
-| **Version** | **0.1.1** |
-| **Hosts** | Claude Code, Grok, or other compatible hosts |
+| **Version** | **0.2.0** |
+| **Hosts** | Claude Code, Grok |
 | **Node** | ≥ 18.18 |
-| **Repository** | [github.com/oppnc/kimi-plugin-cc](https://github.com/oppnc/kimi-plugin-cc) |
-
-> Changelog: [English](CHANGELOG.md) · [中文](CHANGELOG.zh-CN.md)  
-> Contributing: [CONTRIBUTING.md](CONTRIBUTING.md) · Security: [SECURITY.md](SECURITY.md)  
-> For coding agents / maintainers: **[AGENTS.md](AGENTS.md)**
+| **Needs** | Kimi Code CLI installed + `kimi login` |
 
-## Features
+## Happy path (what you use day to day)
 
-| Feature | How |
+| Host | What to do |
 | --- | --- |
-| Full Kimi agent | `kimi acp` → `session/prompt` |
-| Modes | `--mode default\|plan\|auto\|yolo` |
-| Multimodal | `--image` / `--video` / `--media` |
-| Goals | `goal` / `--goal` |
-| Resume | `--resume` / `--session <id>` + `sessions` |
-| Git context (optional) | `--git` / `--base` |
-| Jobs | `status` / `result` / `cancel` |
-| Host UX | `/kimi:rescue` → Agent `kimi-rescue` |
+| **Claude Code** | `/kimi:rescue <frontend or UI task>` |
+| **Grok** | Main agent **must** spawn **`kimi:kimi-rescue`** (or `/kimi:rescue`) for frontend/UI — not implement UI itself |
+| **When (required)** | Frontend/UI, style mocks/reference pages, CSS/layout, screenshot or **video** visual bugs, multi-file implement |
 
-## Requirements
+**Must not** re-implement that work in the main agent when Kimi is ready. Return Kimi’s output as-is.
 
-- Node.js ≥ 18.18
-- [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) installed and logged in (`kimi login`)
-- A compatible host (Claude Code, Grok, …)
+Advanced commands (`/kimi:task`, background jobs, status/result): see [AGENTS.md](AGENTS.md).
 
 ## Install
 
+### Prerequisites
+
+1. Node.js ≥ 18.18  
+2. [Kimi Code CLI](https://github.com/MoonshotAI/kimi-code) + `kimi login`  
+3. If `kimi` is missing from PATH (common on Windows): set `KIMI_CLI_PATH` to the full path of `kimi` / `kimi.exe` (often `%USERPROFILE%\.kimi-code\bin\kimi.exe`)
+
 ### Claude Code
 
 ```text
 /plugin marketplace add oppnc/kimi-plugin-cc
 /plugin install kimi@kimi-code-cc
 ```
 
-Then run `/kimi:setup`. If the new commands are not visible in the current session, run `/reload-plugins` first.
+Then `/kimi:setup`. If commands are missing in the current session: `/reload-plugins`.
 
-To pick up a newer release after install:
+### Grok
 
-```text
-/plugin marketplace update kimi-code-cc
+```bash
+grok plugin install oppnc/kimi-plugin-cc#plugins/kimi --trust
 ```
 
-Then update **kimi** from the Installed tab (or reinstall). Claude Code only refreshes plugins when the declared `version` changes.
+## First verify (do this once)
+
+### 1) Doctor
+
+- Claude: `/kimi:setup`  
+- Or CLI from a checkout:
+
+```bash
+node plugins/kimi/scripts/kimi-companion.mjs setup
+```
+
+You want `acp probe: ok` and a **Next (first verify)** section.
+
+### 2) Hand a frontend task to Kimi
 
-Local path (development):
+**Claude Code:**
 
 ```text
-/plugin marketplace add /absolute/path/to/kimi-plugin-cc
-/plugin install kimi@kimi-code-cc
+/kimi:rescue Implement a small responsive settings section using existing design tokens. Keep changes minimal.
 ```
 
-### Grok
+**Grok:** ask the agent to run the Kimi rescue/handoff for the same frontend task.
+
+**CLI probe** (no host plugin required):
 
 ```bash
-grok plugin install oppnc/kimi-plugin-cc#plugins/kimi --trust
-# or from a local checkout:
-# grok plugin install /path/to/kimi-plugin-cc/plugins/kimi --trust
+node plugins/kimi/scripts/kimi-companion.mjs task --mode yolo -- "Reply with exactly: kimi-bridge-ok"
 ```
 
+If that works, the bridge is healthy. Real work should use `/kimi:rescue` (or Grok equivalent) for frontend/UI.
+
+## Troubleshooting
+
+| Symptom | Fix |
+| --- | --- |
+| `BINARY_NOT_FOUND` | Install Kimi Code; `kimi login`; set `KIMI_CLI_PATH` if needed |
+| `ACP_FAILED` / `LOGIN_REQUIRED` | Run `kimi login` in a normal terminal; re-run setup |
+| `NODE_TOO_OLD` | Upgrade Node to ≥ 18.18 |
+| `MEDIA_NOT_FOUND` | Use an absolute path or a path under the workspace Kimi uses |
+| Commands missing after install | `/reload-plugins`; marketplace update when `version` changes |
+| Plan mode “doesn’t edit files” | By design — use default **yolo** to implement |
+
+Errors are prefixed with `[kimi-plugin]` and include a numbered **Fix** list — show them as-is.
+
+## Compatibility
+
+| Component | Requirement |
+| --- | --- |
+| This plugin | 0.2.0 |
+| Node | ≥ 18.18 |
+| Kimi Code | CLI with working `kimi acp` (NDJSON). Setup prints `compat` + kimi version. Upgrade Kimi Code if ACP fails. |
+
 ## Related
 
 | Package | Host |
 | --- | --- |
 | **kimi-plugin-cc** (this repo) | Claude Code / Grok |
-| [kimi-plugin-codex](https://github.com/oppnc/kimi-plugin-codex) | OpenAI Codex (if published) |
+| [kimi-plugin-codex](https://github.com/oppnc/kimi-plugin-codex) | OpenAI Codex |
 
-## License
-
-MIT — see [LICENSE](./LICENSE).  
-Kimi Code is a separate project with its own license.
+Maintainer / agent details: [AGENTS.md](AGENTS.md) · Changelog: [CHANGELOG.md](CHANGELOG.md)
 
----
+## License
 
-**中文文档:** [README.zh-CN.md](README.zh-CN.md)
+MIT — see [LICENSE](./LICENSE). Kimi Code is a separate project.